from apispec import APISpec from apispec.ext.marshmallow import MarshmallowPlugin from apispec_webframeworks.flask import FlaskPlugin from flask import Flask from marshmallow import Schema, fields # Create an APISpec spec = APISpec( title="Swagger Petstore", version="1.0.0", openapi_version="3.0.2", plugins=[FlaskPlugin(), MarshmallowPlugin()], ) # Optional marshmallow support class CategorySchema(Schema): id = fields.Int() name = fields.Str(required=True) class PetSchema(Schema): category = fields.List(fields.Nested(CategorySchema)) name = fields.Str() # Optional security scheme support api_key_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"} spec.components.security_scheme("ApiKeyAuth", api_key_scheme) # Optional Flask support app = Flask(__name__) @app.route("/random") def random_pet(): """A cute furry animal endpoint.  ---  get:  description: Get a random pet  security:  - ApiKeyAuth: []  responses:  200:  content:  application/json:  schema: PetSchema  """ pet = get_random_pet() return PetSchema().dump(pet) # Register the path and the entities within it with app.test_request_context(): spec.path(view=random_pet)

import json print(json.dumps(spec.to_dict(), indent=2)) # { # "paths": { # "/random": { # "get": { # "description": "Get a random pet", # "security": [ # { # "ApiKeyAuth": [] # } # ], # "responses": { # "200": { # "content": { # "application/json": { # "schema": { # "$ref": "#/components/schemas/Pet" # } # } # } # } # } # } # } # }, # "tags": [], # "info": { # "title": "Swagger Petstore", # "version": "1.0.0" # }, # "openapi": "3.0.2", # "components": { # "parameters": {}, # "responses": {}, # "schemas": { # "Category": { # "type": "object", # "properties": { # "name": { # "type": "string" # }, # "id": { # "type": "integer", # "format": "int32" # } # }, # "required": [ # "name" # ] # }, # "Pet": { # "type": "object", # "properties": { # "name": { # "type": "string" # }, # "category": { # "type": "array", # "items": { # "$ref": "#/components/schemas/Category" # } # } # } # } # "securitySchemes": { # "ApiKeyAuth": { # "type": "apiKey", # "in": "header", # "name": "X-API-Key" # } # } # } # } # } print(spec.to_yaml()) # components: # parameters: {} # responses: {} # schemas: # Category: # properties: # id: {format: int32, type: integer} # name: {type: string} # required: [name] # type: object # Pet: # properties: # category: # items: {$ref: '#/components/schemas/Category'} # type: array # name: {type: string} # type: object # securitySchemes: # ApiKeyAuth: # in: header # name: X-API-KEY # type: apiKey # info: {title: Swagger Petstore, version: 1.0.0} # openapi: 3.0.2 # paths: # /random: # get: # description: Get a random pet # responses: # 200: # content: # application/json: # schema: {$ref: '#/components/schemas/Pet'} # security: # - ApiKeyAuth: [] # tags: []