Welcome to flaskdoc’s documentation!¶
FlaskDoc is an extension of the puparley know to programmatically compose openapi specifications for flask endpoints as a part of code without needing to write a separate yaml file, and it comes with SwaggerUI embedded. Its main focus is on documentation which frees developers to focus on getting their services coded.
User’s Guide¶
This section provides documentation on how to get started using flaskdoc in your application.
Quickstart¶
Install flaskdoc via pip
or add to your project requirements/dependency
$ pip install flaskdoc
Register OpenAPI¶
Add top level openapi objects like Info, Contact, License etc
import flask
from flaskdoc import register_openapi, swagger
app = flask.Flask()
# initialize app, add all the blueprints you care about
# Create top level OpenAPI objects
# the info object
info = swagger.Info(
title="Test",
version="1.2.2",
contact=swagger.Contact(
name="Rowland", email="r.ogwara@gmail.com", url="https://github.com/kulgan"
),
license=swagger.License(name="Apache 2.0", url="https://www.example.com/license"),
)
# servers names and variables if necessary
servers = [swagger.Server(url="http://localhost:15172")]
# top level tags
tags = [
swagger.Tag(name="admin", description="Secured Admin-Only calls"),
swagger.Tag(name="developers", description="Operations available to regular developers"),
]
security_schemes = {
"api_key": swagger.ApiKeySecurityScheme(name="api_key"),
}
# register spec
register_openapi(app, info=info, servers=servers, tags=tags, security=security_schemes)
This adds the following endpoints to your list
/docs
/docs/openapi.yaml
/docs/openapi.json
Start Documenting¶
Now start documenting you flask routes
blp = flask.Blueprint("Dummy", __name__, url_prefix="/v1")
@swagger.POST(
tags=["administrator"],
description="Posts an Echo",
responses={"201": swagger.ResponseObject(description="OK")},
)
@blp.route("/echo", methods=["POST"])
def post():
req = flask.request.get_json(force=True)
return flask.jsonify(req), 200
A GET example with path parameter
blp = flask.Blueprint("Dummy", __name__, url_prefix="/v1")
@swagger.GET(
tags=["getEcho"],
operation_id="getEcho",
parameters=[swagger.PathParameter(name="sample", schema=str)],
description="Retrieve echos wit Get",
responses={
"200": swagger.ResponseObject(
description="Success", content=jo.PlainText(schema=jo.Email()),
)
},
)
@blp.route("/echo/<string:sample>", methods=["GET"])
def echo(sample: str):
"""
Sample GET request
Returns: Echos back whatever was sent
"""
return sample
Run your app and visit /docs to see the generated openapi specs.
Contributing¶
Don’t hesitate to create a Github issue for any bugs or suggestions.