Package: openapi-builder
OpenAPI BuilderAFlaskextension for automatically addingOpenAPIdocumentation to your Flask app.FeaturesOpenAPI Builder is an extension for your RESTful Flask API to easily build OpenAPI (formerly known as Swagger)
documentation using thestandard specification. It is designed to generate the documentation
for your resources, by specifying a few simple parameters per endpoint. OpenAPI Builder is not dependent on a specific
(de-)serialization library (such asmarshmalloworhalogen), since its goal is abstract them. The most powerful
feature of this package is to inspect the (de-)serialization class. Thus, extending your class will automatically
update your documentation. This ensures that your documentation is always up to date.To summarize, the key features are:Generate documentationaccording to the OpenAPI standard. This is the internet standard for writing RESTful API
documentation.Keep documentation up to date.This is due to generating the documentation by inspecting the (de-)serialization
class.Reduce up to 90% development time writing documentation.This is due to automating the repetitive work of writing
documentation.Abstract upon any (de-)serialization class.It works with the parsing library of your choice.How it worksOpenAPI Builder uses theFlaskapplication and schemas to retrieve information about the interaction of your API.
This information is used to generate a specification, which is a JSON-file according to the industry standard Open API
format. This specification can be visualized using any UI that supports the Open API specification, such asSwagger UI, orRedoc.Quick startInstallation is simple via PIP:pipinstallopenapi-builderAfter installation, it’s time to build the documentation for the resources in your Flask application, and expose them
so your external users can read them. For working examples, seethis folder.Initialising the extensionThe extension can be initialized using the following snippet:fromflaskimportFlaskfromopenapi_builderimportOpenApiDocumentationapp=Flask(__name__)# option 1: initialize directlydocumentation=OpenApiDocumentation(app=app)# option 2: add the app later.documentation=OpenApiDocumentation()documentation.init_app(app)The generated documentation is automatically exposed athttp://localhost:5000/documentation. If you
don’t want this, you can disable it in the options. The included documentation UI is taken from
theswagger-codegen page.Adding resourcesAfter the documentation UI has been setup, it’s time to add documentation for your resources. This can be achieved
using theadd_documentationdecorator. Given an example endpoint for your RESTful API, that might look like
this:fromflaskimportFlaskfrommarshmallowimportSchema,fieldsclassUserSchema(Schema):"""User response schema."""name=fields.Str()"""Name of the user."""email=fields.Email()"""Email of the user."""register_date=fields.DateTime()"""When the user was registered."""app=Flask(__name__)# use the same app as used for the UI.@app.route("/users")defusers():"""Returns a list of users, serialized using Marshmallow."""users=[User(name="John",lastname="Doe",email="johndoe@gmail.com"),User(name="Jane",lastname="Doe",email="janedoe@gmail.com"),]returnjsonify(UserSchema(many=True).dumps(users))Documentation for this resource is generated by adding the decorator....fromhttpimportHTTPStatusfromopenapi_builderimportadd_documentation...@app.route("/users")@add_documentation(responses={HTTPStatus.OK:UserSchema(many=True)},summary="Returns a list of users.",description="More extensive information that fully describes the endpoint.",)defusers():...For a full overview of all applicable parameters, seethis configuration page.That’s all folks. You can view your documentation athttp://localhost:5000/documentation, and inspect the configuration
at:http://localhost:5000/documentation-configuration. Whenever the schema is updated by adding/removing/updating a new
property, it is automatically reflected in the OpenAPI documentation.ContributingContributions are welcome! If you can see a way to improve this package:Do click the fork buttonMake your changes and submit a pull request.Or to report a bug or request something new, make an issue.DevelopmentThis section describes development standards for this project.BlackBlackis an uncompromising Python code formatter.
By using it, you cede control over minutiae of hand-formatting.
But in return, you no longer have to worry about formatting your code correctly, since black will handle it.
Blackened code looks the same for all authors, ensuring consistent code formatting within your project.The format used by Black makes code review faster by producing the smaller diffs.Black’s output is always stable.
For a given block of code, a fixed version of black will always produce the same output.
However, it should be noted that different versions of black will produce different outputs.
Black is configured here:requirements-dev.txt,L1.pre-commit-config.yaml,L14,L28, andL47pre-commitThis repository comes with apre-commitstack.
This is a set of git hooks which are executed every time a commit is made.
The hooks catch errors as they occur, and will automatically fix some of these errors.To set up the pre-commit hooks, run the following code from within the repo directory:pip install -r requirements-dev.txt
pre-commit installWhenever trying to commit code which is flagged by the pre-commit hooks, the commit will not go through.
Some of the pre-commit hooks (such asblack,isort) will automatically modify the code to fix the issues.
When this happens, you’ll have to stage the changes made by the commit hooks and then commit again.
Other pre-commit hooks will not modify the code and will just tell you about issues which you’ll then have to manually fix.To run the pre-commit stack on all the files at any time:pre-commit run --all-filesTo force a commit to go through without passing the pre-commit hooks use the--no-verifyflag:git commit --no-verifyThe pre-commit stack which comes with the template is highly opinionated, and includes the following operations:Code is reformatted to use theblackstyle.
Any code inside docstrings will be formatted to black usingblackendocs.
All code cells in Jupyter notebooks are also formatted to black usingblack_nbconvert.All Jupyter notebooks are cleared usingnbstripout.Imports are automatically sorted usingisort.flake8is run to check for conformity to the python style guidePEP-8, along with several other formatting issues.setup-cfg-fmtis used to format any setup.cfg files.Severalhooks from pre-commitare used to screen for non-language specific git issues, such as incomplete git merges, overly large files being committed to the repo, bugged JSON and YAML files.
JSON files are also prettified automatically to have standardised indentation.
Entries in requirements.txt files are automatically sorted alphabetically.Severalhooks from pre-commit specific to pythonare used to screen for rST formatting issues, and ensure noqa flags always specify an error code to ignore.Once it is set up, the pre-commit stack will run locally on every commit.
The pre-commit stack will also run on github with one of the action workflows, which ensures PRs are checked without having to rely on contributors to enable the pre-commit locally.Automated documentationThe scriptdocs/conf.pyis based on theSphinxdefault configuration.
It is set up to work well out of the box, with several features added in.GitHub PagesDocumentation is deployed toGitHub Pagesand is available athttps://flyingbird95.github.io/openapi-builder/.The gh-pages documentation is refreshed every time there is a push to the master branch.Note that only one copy of the documentation is served (the latest version).Building locallyThe web documentation can be built locally with:pip install -r requirements-docs.txt
make -C docs htmlAnd view the documentation like so:sensible-browser docs/_build/html/index.htmlOr build the pdf documentation:make -C docs latexpdfOn Windows, this becomes:cd docs
make html
make latexpdf
cd ..Other documentation featuresThe README.rst will become part of the generated documentation (via a link filedocs/source/readme.rst).
Note that the first line of README.rst is not included in the documentation, since this is expected to contain badges which we render on GitHub, but not include in the documentation pages.The docstrings in all modules, functions, classes and methods will be used to build a set of API documentation usingautodoc.
Ourdocs/conf.pyis also set up to automatically call autodoc whenever it is run, and the output files which it generates are on the gitignore list.
This means it will automatically generate a fresh API description which exactly matches the current docstrings every time the documentation is generated.Docstrings can be formatted in plainreST, or using thenumpy format(recommended), orGoogle format.
Support for numpy and Google formats is through thenapoleonextension (which is enabled by default).The reference functions in the python core and common packages and they will automatically be hyperlinked to the appropriate documentation in the documentation.
This is done usingintersphinxmappings, which can be seen at the bottom of thedocs/conf.pyfile.The documentation theme issphinx-book-theme.
Alternative themes can be found atsphinx-themes.org,sphinxthemes.com, andwritethedocs.Consolidated metadataPackage metadata is consolidated into one place, the fileopenapi_builder/__meta__.py.
This is done to only write the metadata once in this centralised location, and everything else (packaging, documentation, etc) picks it up from there.
This is similar tosingle-sourcing the package version, but for all metadata.This information is available to end-users withimport openapi_builder; print(openapi_builder.__meta__).
The version information is also accessible atopenapi_builder.__version__, as perPEP-396.setup.pyThesetup.pyscript is used to build and install the package.The package can be installed from source with:pip install .or alternatively with:python setup.py installBut do remember that as a developer, the package should be installed in editable mode, using either:pip install --editable .or:python setup.py developwhich will mean changes to the source will affect the installed package immediately without having to reinstall it.By default, when the package is installed only the main requirements, listed inrequirements.txtwill be installed with it.
Requirements listed inrequirements-dev.txt,requirements-docs.txt, andrequirements-test.txtare optional extras.
Thesetup.pyscript is configured to include these as extras nameddev,docs, andtest.
They can be installed along with:pip install .[dev]etc.
Any additional files namedrequirements-EXTRANAME.txtwill also be collected automatically and made available with the corresponding nameEXTRANAME.
Another extra namedallcaptures all of these optional dependencies.The README file is automatically included in the metadata when setup.py build wheels for PyPI.
The rest of the metadata comes fromopenapi_builder/__meta__.py.Our template setup.py file is based on theexample from setuptools documentation, and the comprehensive example fromKenneth Reitz(released underMIT License), with further features added.GitHub Actions WorkflowsGitHub features the ability to run various workflows whenever code is pushed to the repo or a pull request is opened.
This is one service of several services that can be used to continually run the unit tests and ensure changes can be integrated together without issue.
It is also useful to ensure that style guides are adhered toFive workflows are included:docsThe docs workflow ensures the documentation builds correctly, and presents any errors and warnings nicely as annotations.
The available html documentation is automatically deployed to the gh-pages branch andhttps://flyingbird95.github.io/openapi-builder/.pre-commitRuns the pre-commit stack.
Ensures all contributions are compliant, even if a contributor has not set up pre-commit on their local machine.lintChecks the code uses theblackstyle and tests forflake8errors.
Note that the lint workflow is superfluous, due to the pre-commit hooks.testRuns the pytest, and pushes coverage reports toCodecov.release candidate testsThe release candidate tests workflow runs the unit tests on more Python versions and operating systems than the regular test workflow.
This runs on all tags, plus pushes and PRs to branches named like “v1.2.x”, etc.
Wheels are built for all the tested systems, and stored as artifacts for convenience when shipping a new distribution.When thepublishjob is enabled on the release candidate tests workflow, it can also push built release candidates to theTest PyPIserver.