Skip to main content

Extract swagger specs from your flask project

Project description

# flasgger
A Swagger 2.0 spec extractor for Flask

Install:
```
pip install flasgger
```

> Take a look at examples/example.py

flasgger 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.

```
class UserAPI(MethodView):

def post(self):
"""
Create a new user
---
tags:
- users
parameters:
- in: body
name: body
schema:
id: User
required:
- email
- name
properties:
email:
type: string
description: email for user
name:
type: string
description: name for user
address:
description: address for user
schema:
id: Address
properties:
street:
type: string
state:
type: string
country:
type: string
postalcode:
type: string
responses:
201:
description: User created
"""
return {}
```
flasgger supports docstrings in methods of MethodView classes (ala [Flask-RESTful](https://github.com/flask-restful/flask-restful)) and regular Flask view functions.

Following YAML conventions, flasgger 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.

In order to support inline definition of [Schema ](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) objects in [Parameter](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterObject) and [Response](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#responsesObject) objects, flasgger 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.

[Schema ](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) objects can also be defined within the properties of other [Schema ](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject) objects . An example is shown above with the address property of User.

To expose your Swagger specification to the world you provide a Flask route that does something along these lines

```
from flask import Flask, jsonify
from flasgger import Swagger

app = Flask(__name__)

app.config['SWAGGER'] = {
"version": "0.0.1",
"title": "Example site title",
"specs": [
{
"endpoint": 'v1_spec',
"route": '/v1/spec',
"rule_filter": lambda rule: True
},
]
}

# you can pass many specs registers and use rule_filter to
# separate versions

swagger = Swagger() # you can pass config here if prefered

# register your views and blueprints and then

swagger.init_app(app)


if __name__ == "__main__":
app.run(debug=True)

```

If you need to add some aditional info
```
app.config['SWAGGER'] = {
"version": "0.0.1",
"title": "Example site title",
"specs": [
{
"endpoint": 'v1_spec',
"route": '/v1/spec',
"rule_filter": lambda rule: True
"extra_data": {
"info": {"version": "0.1.2"},
"foo": "bar"
}
},
]
}
```


[Swagger-UI](https://github.com/swagger-api/swagger-ui)

Swagger-UI is the reason we embarked on this mission to begin with, flasgger does not however include Swagger-UI. Simply follow the awesome documentation over at https://github.com/swagger-api/swagger-ui and point your [swaggerUi.url](https://github.com/swagger-api/swagger-ui#swaggerui) to your new flasgger endpoint and enjoy.


Acknowledgments

Flasgger is a fork of Flask-Swagger that 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)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

flasgger-0.2.9.tar.gz (6.1 kB view details)

Uploaded Source

File details

Details for the file flasgger-0.2.9.tar.gz.

File metadata

  • Download URL: flasgger-0.2.9.tar.gz
  • Upload date:
  • Size: 6.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for flasgger-0.2.9.tar.gz
Algorithm Hash digest
SHA256 9960d22395bb84e008be7a012c641dd9bf9cc435941aecf4fe62a6a57a247e2d
MD5 96f4efdcb0fdb6087378d6dd5c9f68d9
BLAKE2b-256 1a51e6a6cec8ca2ed717e70ec2ebe7e5eb6471a4077aed600da14b5772b81ddf

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page