Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kulgan/flaskdoc
Flask OpenAPI annotations
https://github.com/kulgan/flaskdoc
api api-docs docs documentation documentation-tool flask models openapi openapi3 swagger
Last synced: about 1 month ago
JSON representation
Flask OpenAPI annotations
- Host: GitHub
- URL: https://github.com/kulgan/flaskdoc
- Owner: kulgan
- License: apache-2.0
- Created: 2019-09-12T21:35:27.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-06-14T12:31:53.000Z (over 3 years ago)
- Last Synced: 2024-11-16T03:11:49.639Z (about 2 months ago)
- Topics: api, api-docs, docs, documentation, documentation-tool, flask, models, openapi, openapi3, swagger
- Language: Python
- Homepage: https://flaskdoc.readthedocs.io
- Size: 7.39 MB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
Awesome Lists containing this project
README
flaskdoc
========
|PyPi version| |Python version| |ci| |docs| |license| |coverage| |code quality|
FlaskDoc allows developers 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.
Why flaskdoc
------------
* Focus only on documentation and not introduce some fancy new way of using flask.
* Easily add to existing code without needing to refactor of change the way the code has been written
* Little or no learning curve, as long as a developer is comforatble using flask developers, they can use flaskdoc.
to learn quickly and not distract So developers focus on writing code
* SwaggerUI integration for quickly testing and iterating through versions
* Automatic data model to JSON Schema transformation that allows for finer grain configuration
Getting Started
---------------
Visit `documentation `_ page for more details.
Install
"""""""
from pypi
.. code-block::
$ pip install flaskdoc
from github
.. code-block::
$ pip install https://github.com/kulgan/flaskdoc/tarball/master
To run examples you will need to install the dev extension
.. code-block::
$ pip install flaskdoc[dev]
Register OpenAPI
""""""""""""""""
Add top level openapi objects like `Info `_,
`Contact `_, `License `_ etc
.. code-block:: python
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="[email protected]", 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
A simple post example
.. code-block:: python
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
.. code-block:: python
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/", 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
Running Examples
================
Two example projects are currently provided
* `inventory `_
* `petstore `_ source `OpenAPI Petstore `_
* `link-example `_ - source `OpenAPI link example `_
* `api-with-example `_ - source `OpenAPI api_with_examples `_
To run
.. code-block:: bash
$ pip install flaskdoc[dev]
$ flaskdoc start -n petstore
Contributing
------------
Don't hesitate to create a `Github issue `__ for any bugs or suggestions
.. |ci| image:: https://github.com/kulgan/flaskdoc/workflows/ci/badge.svg
:target: https://github.com/kulgan/flaskdoc/
:alt: build
.. |PyPi version| image:: https://img.shields.io/pypi/v/flaskdoc.svg
:target: https://pypi.org/project/flaskdoc/
:alt: PyPi downloads
.. |Python version| image:: https://img.shields.io/pypi/pyversions/flaskdoc.svg
:target: https://pypi.org/project/flaskdoc/
:alt: Python versions
.. |license| image:: https://img.shields.io/pypi/l/flaskdoc.svg
:target: https://pypi.org/project/flaskdoc/
:alt: license
.. |docs| image:: https://readthedocs.org/projects/flaskdoc/badge/?version=latest
:target: https://flaskdoc.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. |code quality| image:: https://app.codacy.com/project/badge/Grade/2dafebf021354a42aa62b11d6ab42654
:target: https://www.codacy.com/manual/kulgan/flaskdoc?utm_source=github.com&utm_medium=referral&utm_content=kulgan/flaskdoc&utm_campaign=Badge_Grade
:alt: Code Quality
.. |coverage| image:: https://app.codacy.com/project/badge/Coverage/2dafebf021354a42aa62b11d6ab42654
:target: https://www.codacy.com/manual/kulgan/flaskdoc?utm_source=github.com&utm_medium=referral&utm_content=kulgan/flaskdoc&utm_campaign=Badge_Coverage
:alt: Coverage