Skip to content

Commit 6e48449

Browse files
atlithornatlithorn
committed
fixes getsling#1 using id instead of name
1 parent 51497d4 commit 6e48449

File tree

5 files changed

+124
-15
lines changed

5 files changed

+124
-15
lines changed

‎README

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
flask-swagger
2+
=============
3+
4+
A swagger 2.0 spec extractor for flask
5+
6+
Install:
7+
8+
::
9+
10+
pip install flask-swagger
11+
12+
flask-swagger provides a method (swagger) that inspects the flask app
13+
for endpoints that contain YAML docstrings with swagger 2.0
14+
`Operation <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object>`__
15+
objects.
16+
17+
::
18+
19+
class UserAPI(MethodView):
20+
21+
def post(self):
22+
"""
23+
Create a new user
24+
---
25+
tags:
26+
- users
27+
parameters:
28+
- in: body
29+
name: body
30+
schema:
31+
id: User
32+
required:
33+
- email
34+
- name
35+
properties:
36+
email:
37+
type: string
38+
description: email for user
39+
name:
40+
type: string
41+
description: name for user
42+
responses:
43+
201:
44+
description: User created
45+
"""
46+
return {}
47+
48+
flask-swagger supports docstrings in MethodView classes and regular
49+
flask view functions.
50+
51+
Following YAML conventions, flask-swagger searches for ``---``,
52+
everything preceding is provided as ``summary`` (first line) and
53+
``description`` (following lines) for the endpoint while everything
54+
after is parsed as a swagger
55+
`Operation <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object>`__
56+
object.
57+
58+
In order to support inline definition of
59+
`Schema <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject>`__
60+
objects in
61+
`Operation <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object>`__
62+
and
63+
`Response <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responsesObject>`__
64+
items, flask-swagger veers a little off from the standard. We require an
65+
``id`` field for the inline Schema which is then used to correctly place
66+
the
67+
`Schema <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject>`__
68+
object in the
69+
`Definitions <https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#definitionsObject>`__
70+
object.
71+
72+
To expose your swagger specification to the world you provide a flask
73+
route that does something along these lines
74+
75+
::
76+
77+
from flask import Flask, jsonify
78+
from flask_swagger import swagger
79+
80+
app = Flask(__name__)
81+
82+
@app.route("/spec")
83+
def spec():
84+
return jsonify(swagger(app))
85+
86+
Note that the swagger specification returned by ``swagger(app)`` is as
87+
minimal as it can be. It's your job to override and add to the
88+
specification as you see fit.
89+
90+
::
91+
92+
@app.route("/spec")
93+
def spec():
94+
swag = swagger(app)
95+
swag['info']['version'] = "1.0"
96+
swag['info']['title'] = "My API"
97+
return jsonify(swag)
98+
99+
`Swagger-UI <https://github.com/swagger-api/swagger-ui>`__
100+
101+
Swagger-UI is the reason we embarked on this mission to begin with,
102+
flask-swagger does not however include Swagger-UI. Simply follow the
103+
awesome documentation over at https://github.com/swagger-api/swagger-ui
104+
and point your
105+
`swaggerUi.url <https://github.com/swagger-api/swagger-ui#swaggerui>`__
106+
to your new flask-swagger endpoint and enjoy.
107+
108+
Acknowledgments
109+
110+
flask-swagger builds on ideas and code from
111+
`flask-sillywalk <https://github.com/hobbeswalsh/flask-sillywalk>`__ and
112+
`flask-restful-swagger <https://github.com/rantav/flask-restful-swagger>`__

‎README.md

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Install:
55
```
66
pip install flask-swagger
77
```
8-
flask-swagger provides a method (swagger) that inspects the flask app for endpoints that contain YAML docstrings with swagger 2.0 [Operation](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object) objects.
8+
flask-swagger provides a method (swagger) that inspects the flask app for endpoints that contain YAML docstrings with swagger 2.0 [Operation](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object) objects.
99

1010
```
1111
class UserAPI(MethodView):
@@ -20,7 +20,7 @@ class UserAPI(MethodView):
2020
- in: body
2121
name: body
2222
schema:
23-
name: User
23+
id: User
2424
required:
2525
- email
2626
- name
@@ -41,7 +41,7 @@ flask-swagger supports docstrings in MethodView classes and regular flask view f
4141

4242
Following YAML conventions, flask-swagger searches for `---`, everything preceding is provided as `summary` (first line) and `description` (following lines) for the endpoint while everything after is parsed as a swagger [Operation](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object) object.
4343

44-
In order to support inline definition of [Schema ](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) objects in [Operation](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object) and [Response](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responsesObject) items, flask-swagger veers a little off from the standard. We add (and require) a `name` field for the inline Schema which is then used to correctly place the [Schema](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) object in the [Definitions](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#definitionsObject) object.
44+
In order to support inline definition of [Schema ](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) objects in [Operation](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#operation-object) and [Response](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responsesObject) items, flask-swagger veers a little off from the standard. We require an `id` field for the inline Schema which is then used to correctly place the [Schema](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) object in the [Definitions](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#definitionsObject) object.
4545

4646
To expose your swagger specification to the world you provide a flask route that does something along these lines
4747

@@ -75,5 +75,3 @@ Swagger-UI is the reason we embarked on this mission to begin with, flask-swagge
7575
Acknowledgments
7676

7777
flask-swagger builds on ideas and code from [flask-sillywalk](https://github.com/hobbeswalsh/flask-sillywalk) and [flask-restful-swagger](https://github.com/rantav/flask-restful-swagger)
78-
79-

‎examples/example.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ def post(self):
3030
- in: body
3131
name: body
3232
schema:
33-
name: User
33+
id: User
3434
required:
3535
- email
3636
- name
@@ -71,7 +71,7 @@ def bla():
7171
200:
7272
description: Hacked some hacks
7373
schema:
74-
name: Hack
74+
id: Hack
7575
properties:
7676
hack:
7777
type: string

‎flask_swagger.py

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,11 @@ def _extract_definitions(alist):
4545
for params in alist:
4646
schema = params.get("schema")
4747
if schema is not None:
48-
schema_name = schema.get("name")
49-
if schema_name is not None:
48+
schema_id = schema.get("id")
49+
if schema_id is not None:
5050
defs.append(schema)
5151
params['schema'] = {
52-
"$ref": "#/definitions/{}".format(schema_name)
52+
"$ref": "#/definitions/{}".format(schema_id)
5353
}
5454
return defs
5555

@@ -100,9 +100,9 @@ def spec():
100100
if responses is not None:
101101
defs = defs + _extract_definitions(responses.values())
102102
for definition in defs:
103-
name = definition.get('name')
104-
if name is not None:
105-
definitions[name] = definition
103+
def_id = definition.get('id')
104+
if def_id is not None:
105+
definitions[def_id] = definition
106106
operations[verb] = dict(
107107
summary=summary,
108108
description=description,

‎setup.py

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,11 @@
77
long_description = file.read()
88

99
setup(name='flask-swagger',
10-
version='0.1.1',
10+
version='0.2.0',
1111
url='https://github.com/gangverk/flask-swagger',
1212
description='Extract swagger specs from your flast-restful project',
1313
author='Atli Thorbjornsson',
1414
license='MIT',
1515
py_modules=['flask_swagger'],
1616
long_description=long_description,
1717
install_requires=['Flask>=0.10', 'PyYAML>=3.0'])
18-

0 commit comments

Comments
 (0)