pecalleja / flask-redoc

A Flask extension for displaying OpenAPI/Swagger documentation using Redocs

flask-redoc

A Flask extension for displaying OpenAPI/Swagger documentation using Redocs.

Installation

Under your virtualenv do:

pip install flask-redoc

or (dev version)

pip install https://github.com/mzaglia/flask-redoc

Getting Started

Using YAML file

Save your petstore.yml

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

Load in your app:

from flask import Flask
from flask_redoc import Redoc

redoc = Redoc(app,'petstore.yml')

@app.route('/pets', methods=['GET', 'POST'])
def pets():
    ...

You can also use docstrings as specification and Marshmallow models for schemas (this will updated any existing specs loaded with YAML files).

app.config['REDOC'] = {'title':'Petstore', 'marshmallow_schemas':[PetSchema]}

class PetSchema(Schema):
    name = fields.Str()

@app.route('/random')
def random():
    """A cute furry animal endpoint.
    ---
    get:
      description: Get a random pet
      responses:
        200:
          description: Return a pet
          content:
            application/json:
              schema: PetSchema
    """
    return PetSchema().dump(dict(name="Bird"))

Configuration

Default configuration

 DEFAULT_CONFIG = {
        'endpoint': 'docs',
        'spec_route': '/docs',
        'static_url_path': '/redoc_static',
        'title': 'ReDoc',
        'version': '1.0.0',
        'openapi_version': '3.0.2',
        'info': dict(),
        'marshmallow_schemas': list()
    }

Changing configuration

You can change any default configuration as follows

app.config['REDOC'] = {'spec_route': '/my_docs', 'title': 'My Docs'}
redoc = Redoc(app)

Further reading

For more information about creating your spec using docstring, please visit: https://apispec.readthedocs.io/en/latest/