Skip to content

Commit dd5ba6a

Browse files
sloriasloria
committed
Update docs to use OAS 3
* Update all examples to use OAS 3.0.2 * Update links to point to 3.0.2 spec close #377
1 parent 4baa95c commit dd5ba6a

File tree

9 files changed

+291
-235
lines changed

9 files changed

+291
-235
lines changed

‎README.rst

Lines changed: 87 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,7 @@ A pluggable API specification generator. Currently supports the `OpenAPI Specifi
2323
Features
2424
========
2525

26-
- Supports OpenAPI Specification version 2 (f.k.a. the Swagger specification)
27-
with limited support for version 3
26+
- Supports the OpenAPI Specification (versions 2 and 3)
2827
- Framework-agnostic
2928
- Built-in support for `marshmallow <https://marshmallow.readthedocs.io/>`_
3029
- Utilities for parsing docstrings
@@ -45,7 +44,7 @@ Example Application
4544
spec = APISpec(
4645
title='Swagger Petstore',
4746
version='1.0.0',
48-
openapi_version='2.0',
47+
openapi_version='3.0.2',
4948
plugins=[
5049
FlaskPlugin(),
5150
MarshmallowPlugin(),
@@ -69,18 +68,19 @@ Example Application
6968
"""A cute furry animal endpoint.
7069
---
7170
get:
72-
description: Get a random pet
73-
responses:
74-
200:
75-
description: A pet to be returned
76-
schema: PetSchema
71+
description: Get a random pet
72+
responses:
73+
200:
74+
content:
75+
application/json:
76+
schema: PetSchema
7777
"""
7878
pet = get_random_pet()
7979
return jsonify(PetSchema().dump(pet).data)
8080
8181
# Register entities and paths
82-
spec.definition('Category', schema=CategorySchema)
83-
spec.definition('Pet', schema=PetSchema)
82+
spec.components.schema('Category', schema=CategorySchema)
83+
spec.components.schema('Pet', schema=PetSchema)
8484
with app.test_request_context():
8585
spec.path(view=random_pet)
8686
@@ -90,79 +90,106 @@ Generated OpenAPI Spec
9090

9191
.. code-block:: python
9292
93-
spec.to_dict()
93+
import json
94+
print(json.dumps(spec.to_dict(), indent=2))
9495
# {
95-
# "info": {
96-
# "title": "Swagger Petstore",
97-
# "version": "1.0.0"
98-
# },
99-
# "swagger": "2.0",
10096
# "paths": {
10197
# "/random": {
10298
# "get": {
103-
# "description": "A cute furry animal endpoint.",
99+
# "description": "Get a random pet",
104100
# "responses": {
105101
# "200": {
106-
# "schema": {
107-
# "$ref": "#/definitions/Pet"
108-
# },
109-
# "description": "A pet to be returned"
102+
# "content": {
103+
# "application/json": {
104+
# "schema": {
105+
# "$ref": "#/components/schemas/Pet"
106+
# }
107+
# }
108+
# }
110109
# }
111-
# },
110+
# }
112111
# }
113112
# }
114113
# },
115-
# "definitions": {
116-
# "Pet": {
117-
# "properties": {
118-
# "category": {
119-
# "type": "array",
120-
# "items": {
121-
# "$ref": "#/definitions/Category"
114+
# "tags": [],
115+
# "info": {
116+
# "title": "Swagger Petstore",
117+
# "version": "1.0.0"
118+
# },
119+
# "openapi": "3.0.2",
120+
# "components": {
121+
# "parameters": {},
122+
# "responses": {},
123+
# "schemas": {
124+
# "Category": {
125+
# "type": "object",
126+
# "properties": {
127+
# "name": {
128+
# "type": "string"
129+
# },
130+
# "id": {
131+
# "type": "integer",
132+
# "format": "int32"
122133
# }
123134
# },
124-
# "name": {
125-
# "type": "string"
126-
# }
127-
# }
128-
# },
129-
# "Category": {
130-
# "required": [
131-
# "name"
132-
# ],
133-
# "properties": {
134-
# "name": {
135-
# "type": "string"
136-
# },
137-
# "id": {
138-
# "type": "integer",
139-
# "format": "int32"
135+
# "required": [
136+
# "name"
137+
# ]
138+
# },
139+
# "Pet": {
140+
# "type": "object",
141+
# "properties": {
142+
# "name": {
143+
# "type": "string"
144+
# },
145+
# "category": {
146+
# "type": "array",
147+
# "items": {
148+
# "$ref": "#/components/schemas/Category"
149+
# }
150+
# }
140151
# }
141152
# }
142153
# }
143-
# },
154+
# }
144155
# }
145156
146-
spec.to_yaml()
147-
# definitions:
148-
# Pet:
149-
# enum: [name, photoUrls]
150-
# properties:
151-
# id: {format: int64, type: integer}
152-
# name: {example: doggie, type: string}
153-
# info: {description: 'This is a sample Petstore server. You can find out more ', title: Swagger Petstore, version: 1.0.0}
154-
# parameters: {}
155-
# paths: {}
156-
# security:
157-
# - apiKey: []
158-
# swagger: '2.0'
157+
print(spec.to_yaml())
158+
# components:
159+
# parameters: {}
160+
# responses: {}
161+
# schemas:
162+
# Category:
163+
# properties:
164+
# id: {format: int32, type: integer}
165+
# name: {type: string}
166+
# required: [name]
167+
# type: object
168+
# Pet:
169+
# properties:
170+
# category:
171+
# items: {$ref: '#/components/schemas/Category'}
172+
# type: array
173+
# name: {type: string}
174+
# type: object
175+
# info: {title: Swagger Petstore, version: 1.0.0}
176+
# openapi: 3.0.2
177+
# paths:
178+
# /random:
179+
# get:
180+
# description: Get a random pet
181+
# responses:
182+
# 200:
183+
# content:
184+
# application/json:
185+
# schema: {$ref: '#/components/schemas/Pet'}
159186
# tags: []
160187
161188
162189
Documentation
163190
=============
164191

165-
Documentation is available at http://apispec.readthedocs.io/ .
192+
Documentation is available at https://apispec.readthedocs.io/ .
166193

167194
Ecosystem
168195
=========

‎apispec/core.py

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ def clean_operations(operations, openapi_major_version):
2929
as required by the OpenAPI specification, as well as normalizing any
3030
references to global parameters. Also checks for invalid HTTP methods.
3131
32-
See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject.
32+
See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject.
3333
3434
:param dict operations: Dict mapping status codes to operations
3535
:param int openapi_major_version: The major version of the OpenAPI standard
@@ -90,8 +90,8 @@ def get_ref(obj_type, obj, openapi_major_version):
9090
class Components(object):
9191
"""Stores OpenAPI components
9292
93-
Components are top-level fields in Openapi v2.
94-
They became sub-fields of "components" top-level field in Openapi v3.
93+
Components are top-level fields in OAS v2.
94+
They became sub-fields of "components" top-level field in OAS v3.
9595
"""
9696
def __init__(self, plugins, openapi_version):
9797
self._plugins = plugins
@@ -127,7 +127,7 @@ def schema(
127127
description='Status (open or closed)',
128128
)
129129
130-
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#definitionsObject
130+
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject
131131
"""
132132
if name in self._schemas:
133133
raise DuplicateComponentNameError(
@@ -201,11 +201,11 @@ class APISpec(object):
201201
:param str title: API title
202202
:param str version: API version
203203
:param list|tuple plugins: Plugin instances.
204-
See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#infoObject
204+
See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#infoObject
205205
:param str|OpenAPIVersion openapi_version: The OpenAPI version to use.
206206
Should be in the form '2.x' or '3.x.x' to comply with the OpenAPI standard.
207207
:param dict options: Optional top-level keys
208-
See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swagger-object
208+
See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-object
209209
"""
210210
def __init__(self, title, version, openapi_version, plugins=(), **options):
211211
self.title = title
@@ -259,7 +259,7 @@ def tag(self, tag):
259259
def path(self, path=None, operations=None, **kwargs):
260260
"""Add a new path object to the spec.
261261
262-
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathsObject
262+
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#path-item-object
263263
264264
:param str|None path: URL path component
265265
:param dict|None operations: describes the http methods and options for `path`

‎apispec/ext/marshmallow/openapi.py

Lines changed: 20 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
# -*- coding: utf-8 -*-
2-
"""Utilities for generating OpenAPI spec (fka Swagger) entities from
2+
"""Utilities for generating OpenAPI Specification (fka Swagger) entities from
33
marshmallow :class:`Schemas <marshmallow.Schema>` and :class:`Fields <marshmallow.fields.Field>`.
4-
5-
OpenAPI 2.0 spec: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
64
"""
75
from __future__ import absolute_import, unicode_literals
86
import operator
@@ -61,7 +59,7 @@
6159

6260
# Properties that may be defined in a field's metadata that will be added to the output
6361
# of field2property
64-
# https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject
62+
# https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject
6563
_VALID_PROPERTIES = {
6664
'format',
6765
'title',
@@ -334,11 +332,11 @@ def metadata2properties(self, field):
334332
335333
Will include field metadata that are valid properties of `OpenAPI schema
336334
objects
337-
<https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject>`_
335+
<https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject>`_
338336
(e.g. “description”, “enum”, “example”).
339337
340338
In addition, `specification extensions
341-
<https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#patterned-objects-9>`_
339+
<https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#specification-extensions>`_
342340
are supported. Prefix `x_` to the desired extension when passing the
343341
keyword argument to the field constructor. apispec will convert `x_` to
344342
`x-` to comply with OpenAPI.
@@ -366,7 +364,7 @@ def field2property(self, field, use_refs=True, name=None):
366364
Will include field metadata that are valid properties of OpenAPI schema objects
367365
(e.g. "description", "enum", "example").
368366
369-
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject
367+
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject
370368
371369
:param Field field: A marshmallow field.
372370
:param bool use_refs: Use JSONSchema ``refs``.
@@ -477,7 +475,7 @@ def schema2parameters(
477475
of a single parameter; else return an array of a parameter for each included field in
478476
the :class:`Schema <marshmallow.Schema>`.
479477
480-
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject
478+
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
481479
"""
482480
openapi_default_in = __location_map__.get(default_in, default_in)
483481
if self.openapi_version.major < 3 and openapi_default_in == 'body':
@@ -508,15 +506,13 @@ def fields2parameters(self, fields, use_refs=True, default_in='body'):
508506
of a single parameter; else return an array of a parameter for each included field in
509507
the :class:`Schema <marshmallow.Schema>`.
510508
511-
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject
512-
513509
In OpenAPI3, only "query", "header", "path" or "cookie" are allowed for the location
514510
of parameters. In OpenAPI 3, "requestBody" is used when fields are in the body.
515511
516512
This function always returns a list, with a parameter
517513
for each included field in the :class:`Schema <marshmallow.Schema>`.
518514
519-
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#parameterObject
515+
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
520516
"""
521517
parameters = []
522518
body_param = None
@@ -544,7 +540,7 @@ def field2parameter(self, field, name='body', use_refs=True, default_in='body'):
544540
"""Return an OpenAPI parameter as a `dict`, given a marshmallow
545541
:class:`Field <marshmallow.Field>`.
546542
547-
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject
543+
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
548544
"""
549545
location = field.metadata.get('location', None)
550546
prop = self.field2property(field, use_refs=use_refs)
@@ -563,7 +559,7 @@ def property2parameter(
563559
):
564560
"""Return the Parameter Object definition for a JSON Schema property.
565561
566-
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject
562+
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#parameterObject
567563
568564
:param dict prop: JSON Schema property
569565
:param str name: Field name
@@ -610,7 +606,7 @@ def schema2jsonschema(self, schema, **kwargs):
610606
:class:`Schema <marshmallow.Schema>`. Schema may optionally provide the ``title`` and
611607
``description`` class Meta options.
612608
613-
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject
609+
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schemaObject
614610
615611
Example: ::
616612
@@ -623,23 +619,16 @@ class Meta:
623619
title = 'User'
624620
description = 'A registered user'
625621
626-
OpenAPI.schema2jsonschema(UserSchema)
627-
# {
628-
# 'title': 'User', 'description': 'A registered user',
629-
# 'properties': {
630-
# 'name': {'required': False,
631-
# 'description': '',
632-
# 'type': 'string'},
633-
# '_id': {'format': 'int32',
634-
# 'required': False,
635-
# 'description': '',
636-
# 'type': 'integer'},
637-
# 'email': {'format': 'email',
638-
# 'required': False,
639-
# 'description': 'email address of the user',
640-
# 'type': 'string'}
641-
# }
642-
# }
622+
oaic = OpenAPIConverter(openapi_version='3.0.2', schema_name_resolver=resolver, spec=spec)
623+
pprint(oaic.schema2jsonschema(UserSchema))
624+
# {'description': 'A registered user',
625+
# 'properties': {'_id': {'format': 'int32', 'type': 'integer'},
626+
# 'email': {'description': 'email address of the user',
627+
# 'format': 'email',
628+
# 'type': 'string'},
629+
# 'name': {'type': 'string'}},
630+
# 'title': 'User',
631+
# 'type': 'object'}
643632
644633
:param Schema schema: A marshmallow Schema instance or a class object
645634
:rtype: dict, a JSON Schema Object

‎apispec/plugin.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ def path_helper(self, path=None, operations=None, **kwargs):
2929
3030
:param str path: Path to the resource
3131
:param dict operations: A `dict` mapping HTTP methods to operation object. See
32-
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operationObject
32+
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject
3333
3434
Return value should be a string or None. If a string is returned, it
3535
is set as the path.

0 commit comments

Comments
 (0)