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