1******* 2apispec 3******* 4 5Release v\ |version| (:doc:`Changelog <changelog>`) 6 7A pluggable API specification generator. Currently supports the `OpenAPI Specification <https://github.com/OAI/OpenAPI-Specification>`_ (f.k.a. the Swagger specification). 8 9Features 10======== 11 12- Supports the OpenAPI Specification (versions 2 and 3) 13- Framework-agnostic 14- Built-in support for `marshmallow <https://marshmallow.readthedocs.io/>`_ 15- Utilities for parsing docstrings 16 17Example Application 18=================== 19 20.. code-block:: python 21 22 import uuid 23 24 from apispec import APISpec 25 from apispec.ext.marshmallow import MarshmallowPlugin 26 from apispec_webframeworks.flask import FlaskPlugin 27 from flask import Flask 28 from marshmallow import Schema, fields 29 30 31 # Create an APISpec 32 spec = APISpec( 33 title="Swagger Petstore", 34 version="1.0.0", 35 openapi_version="3.0.2", 36 plugins=[FlaskPlugin(), MarshmallowPlugin()], 37 ) 38 39 # Optional marshmallow support 40 class CategorySchema(Schema): 41 id = fields.Int() 42 name = fields.Str(required=True) 43 44 45 class PetSchema(Schema): 46 categories = fields.List(fields.Nested(CategorySchema)) 47 name = fields.Str() 48 49 50 # Optional security scheme support 51 api_key_scheme = {"type": "apiKey", "in": "header", "name": "X-API-Key"} 52 spec.components.security_scheme("ApiKeyAuth", api_key_scheme) 53 54 55 # Optional Flask support 56 app = Flask(__name__) 57 58 59 @app.route("/random") 60 def random_pet(): 61 """A cute furry animal endpoint. 62 --- 63 get: 64 description: Get a random pet 65 security: 66 - ApiKeyAuth: [] 67 responses: 68 200: 69 description: Return a pet 70 content: 71 application/json: 72 schema: PetSchema 73 """ 74 # Hardcoded example data 75 pet_data = { 76 "name": "sample_pet_" + str(uuid.uuid1()), 77 "categories": [{"id": 1, "name": "sample_category"}], 78 } 79 return PetSchema().dump(pet_data) 80 81 82 # Register the path and the entities within it 83 with app.test_request_context(): 84 spec.path(view=random_pet) 85 86 87Generated OpenAPI Spec 88---------------------- 89 90.. code-block:: python 91 92 import json 93 94 print(json.dumps(spec.to_dict(), indent=2)) 95 # { 96 # "info": { 97 # "title": "Swagger Petstore", 98 # "version": "1.0.0" 99 # }, 100 # "openapi": "3.0.2", 101 # "components": { 102 # "schemas": { 103 # "Category": { 104 # "type": "object", 105 # "properties": { 106 # "id": { 107 # "type": "integer", 108 # "format": "int32" 109 # }, 110 # "name": { 111 # "type": "string" 112 # } 113 # }, 114 # "required": [ 115 # "name" 116 # ] 117 # }, 118 # "Pet": { 119 # "type": "object", 120 # "properties": { 121 # "categories": { 122 # "type": "array", 123 # "items": { 124 # "$ref": "#/components/schemas/Category" 125 # } 126 # }, 127 # "name": { 128 # "type": "string" 129 # } 130 # } 131 # }, 132 # } 133 # }, 134 # "securitySchemes": { 135 # "ApiKeyAuth": { 136 # "type": "apiKey", 137 # "in": "header", 138 # "name": "X-API-Key" 139 # } 140 # }, 141 # "paths": { 142 # "/random": { 143 # "get": { 144 # "description": "Get a random pet", 145 # "security": [ 146 # { 147 # "ApiKeyAuth": [] 148 # } 149 # ], 150 # "responses": { 151 # "200": { 152 # "description": "Return a pet", 153 # "content": { 154 # "application/json": { 155 # "schema": { 156 # "$ref": "#/components/schemas/Pet" 157 # } 158 # } 159 # } 160 # } 161 # } 162 # } 163 # } 164 # }, 165 # } 166 167 print(spec.to_yaml()) 168 # info: 169 # title: Swagger Petstore 170 # version: 1.0.0 171 # openapi: 3.0.2 172 # components: 173 # schemas: 174 # Category: 175 # properties: 176 # id: 177 # format: int32 178 # type: integer 179 # name: 180 # type: string 181 # required: 182 # - name 183 # type: object 184 # Pet: 185 # properties: 186 # categories: 187 # items: 188 # $ref: '#/components/schemas/Category' 189 # type: array 190 # name: 191 # type: string 192 # type: object 193 # securitySchemes: 194 # ApiKeyAuth: 195 # in: header 196 # name: X-API-KEY 197 # type: apiKey 198 # paths: 199 # /random: 200 # get: 201 # description: Get a random pet 202 # responses: 203 # '200': 204 # content: 205 # application/json: 206 # schema: 207 # $ref: '#/components/schemas/Pet' 208 # description: Return a pet 209 # security: 210 # - ApiKeyAuth: [] 211 212User Guide 213========== 214 215.. toctree:: 216 :maxdepth: 2 217 218 install 219 quickstart 220 using_plugins 221 writing_plugins 222 special_topics 223 224API Reference 225============= 226 227.. toctree:: 228 :maxdepth: 2 229 230 api_core 231 api_ext 232 233Project Links 234============= 235 236- `apispec @ GitHub <https://github.com/marshmallow-code/apispec>`_ 237- `Issue Tracker <https://github.com/marshmallow-code/apispec/issues>`_ 238 239Project Info 240============ 241 242.. toctree:: 243 :maxdepth: 1 244 245 changelog 246 upgrading 247 ecosystem 248 authors 249 contributing 250 license 251