{"id":14065189,"url":"https://github.com/FlyingBird95/openapi-builder","last_synced_at":"2025-07-29T20:31:35.413Z","repository":{"id":40577292,"uuid":"428424952","full_name":"FlyingBird95/openapi-builder","owner":"FlyingBird95","description":"A Flask extension to automatically add OpenAPI documentation for your Flask app. ","archived":false,"fork":false,"pushed_at":"2023-12-11T16:00:05.000Z","size":2614,"stargazers_count":7,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-23T04:56:56.917Z","etag":null,"topics":["blueprint","flask","flask-extension","openapi","openapi-documentation","openapi-generator","openapi-specification","python","swagger","swagger-documentation"],"latest_commit_sha":null,"homepage":"https://flyingbird95.github.io/openapi-builder","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FlyingBird95.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-15T21:20:13.000Z","updated_at":"2024-05-28T00:29:49.568Z","dependencies_parsed_at":"2024-05-28T00:29:47.049Z","dependency_job_id":"090d8e7d-87de-46f2-b3dd-7c245be1e75c","html_url":"https://github.com/FlyingBird95/openapi-builder","commit_stats":{"total_commits":117,"total_committers":2,"mean_commits":58.5,"dds":"0.042735042735042694","last_synced_commit":"685b8bca4fcea67ae3b62a644264bfb29283e923"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlyingBird95%2Fopenapi-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlyingBird95%2Fopenapi-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlyingBird95%2Fopenapi-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlyingBird95%2Fopenapi-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FlyingBird95","download_url":"https://codeload.github.com/FlyingBird95/openapi-builder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228046116,"owners_count":17861101,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blueprint","flask","flask-extension","openapi","openapi-documentation","openapi-generator","openapi-specification","python","swagger","swagger-documentation"],"created_at":"2024-08-13T07:04:21.469Z","updated_at":"2024-12-04T04:30:51.744Z","avatar_url":"https://github.com/FlyingBird95.png","language":"Python","readme":"|GHA tests| |Documentation| |Codecov report| |pre-commit| |black| |pypi| |downloads|\n\n`OpenAPI Builder \u003chttps://flyingbird95.github.io/openapi-builder\u003e`_\n===================================================================\nA Flask_ extension for automatically adding OpenAPI_ documentation to your Flask app.\n\n.. _Flask: https://flask.palletsprojects.com/\n.. _OpenAPI: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md\n\n\nFeatures\n--------\nOpenAPI Builder is an extension for your RESTful Flask API to easily build OpenAPI (formerly known as Swagger)\ndocumentation using the `standard specification \u003cstandard_specification_\u003e`_. It is designed to generate the documentation\nfor your resources, by specifying a few simple parameters per endpoint. OpenAPI Builder is not dependent on a specific\n(de-)serialization library (such as marshmallow_ or halogen_), since its goal is abstract them. The most powerful\nfeature of this package is to inspect the (de-)serialization class. Thus, extending your class will automatically\nupdate your documentation. This ensures that your documentation is always up to date.\n\nTo summarize, the key features are:\n\n- **Generate documentation** according to the OpenAPI standard. This is the internet standard for writing RESTful API\n  documentation.\n- **Keep documentation up to date.** This is due to generating the documentation by inspecting the (de-)serialization\n  class.\n- **Reduce up to 90% development time writing documentation.** This is due to automating the repetitive work of writing\n  documentation.\n- **Abstract upon any (de-)serialization class.** It works with the parsing library of your choice.\n\n.. _standard_specification: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md\n.. _marshmallow: https://marshmallow.readthedocs.io/en/stable/\n.. _halogen: https://halogen.readthedocs.io/en/latest/\n\nHow it works\n------------\n.. image:: img/flow-diagram.png\n\nOpenAPI Builder uses the Flask_ application and schemas to retrieve information about the interaction of your API.\nThis information is used to generate a specification, which is a JSON-file according to the industry standard Open API\nformat. This specification can be visualized using any UI that supports the Open API specification, such as\n`Swagger UI \u003cswagger_ui_\u003e`_, or Redoc_.\n\n|swagger| |redoc|\n\n.. |swagger| image:: img/swagger-ui.png\n  :width: 45%\n.. |redoc| image:: img/redoc-ui.png\n  :width: 45%\n\n.. _Flask: https://flask.palletsprojects.com/\n.. _swagger_ui: https://swagger.io/tools/swagger-ui/\n.. _Redoc: https://redoc.ly/\n\nQuick start\n-----------\nInstallation is simple via PIP:\n\n.. code:: bash\n\n    pip install openapi-builder\n\nAfter installation, it's time to build the documentation for the resources in your Flask application, and expose them\nso your external users can read them. For working examples, see `this folder \u003cthis-folder_\u003e`_.\n\n.. _this-folder: https://github.com/FlyingBird95/openapi-builder/tree/master/examples/\n\nInitialising the extension\n~~~~~~~~~~~~~~~~~~~~~~~~~~\nThe extension can be initialized using the following snippet:\n\n.. code:: python\n\n    from flask import Flask\n    from openapi_builder import OpenApiDocumentation\n\n    app = Flask(__name__)\n\n    # option 1: initialize directly\n    documentation = OpenApiDocumentation(app=app)\n\n    # option 2: add the app later.\n    documentation = OpenApiDocumentation()\n    documentation.init_app(app)\n\nThe generated documentation is automatically exposed at http://localhost:5000/documentation. If you\ndon't want this, you can disable it in the options. The included documentation UI is taken from\nthe `swagger-codegen page \u003cswagger_\u003e`_.\n\n.. _swagger: https://github.com/swagger-api/swagger-codegen\n\n\nAdding resources\n~~~~~~~~~~~~~~~~\nAfter the documentation UI has been setup, it's time to add documentation for your resources. This can be achieved\nusing the :code:`add_documentation` decorator. Given an example endpoint for your RESTful API, that might look like\nthis:\n\n\n.. code:: python\n\n    from flask import Flask\n    from marshmallow import Schema, fields\n\n\n    class UserSchema(Schema):\n        \"\"\"User response schema.\"\"\"\n\n        name = fields.Str()\n        \"\"\"Name of the user.\"\"\"\n\n        email = fields.Email()\n        \"\"\"Email of the user.\"\"\"\n\n        register_date = fields.DateTime()\n        \"\"\"When the user was registered.\"\"\"\n\n\n    app = Flask(__name__)  # use the same app as used for the UI.\n\n\n    @app.route(\"/users\")\n    def users():\n        \"\"\"Returns a list of users, serialized using Marshmallow.\"\"\"\n        users = [\n            User(name=\"John\", lastname=\"Doe\", email=\"johndoe@gmail.com\"),\n            User(name=\"Jane\", lastname=\"Doe\", email=\"janedoe@gmail.com\"),\n        ]\n        return jsonify(UserSchema(many=True).dumps(users))\n\nDocumentation for this resource is generated by adding the decorator.\n\n\n.. code:: python\n\n    ...\n    from http import HTTPStatus\n    from openapi_builder import add_documentation\n\n    ...\n\n\n    @app.route(\"/users\")\n    @add_documentation(\n        responses={HTTPStatus.OK: UserSchema(many=True)},\n        summary=\"Returns a list of users.\",\n        description=\"More extensive information that fully describes the endpoint.\",\n    )\n    def users():\n        ...\n\n\nFor a full overview of all applicable parameters, see `this configuration page \u003cdoc-page_\u003e`_.\n\nThat's all folks. You can view your documentation at http://localhost:5000/documentation, and inspect the configuration\nat: http://localhost:5000/documentation-configuration. Whenever the schema is updated by adding/removing/updating a new\nproperty, it is automatically reflected in the OpenAPI documentation.\n\n.. _doc-page: https://flyingbird95.github.io/openapi-builder/configuration.html\n\n\nContributing\n------------\n\nContributions are welcome! If you can see a way to improve this package:\n\n- Do click the fork button\n- Make your changes and submit a pull request.\n\nOr to report a bug or request something new, make an issue.\n\n\nDevelopment\n-----------\nThis section describes development standards for this project.\n\nBlack\n~~~~~\n\nBlack_ is an uncompromising Python code formatter.\nBy using it, you cede control over minutiae of hand-formatting.\nBut in return, you no longer have to worry about formatting your code correctly, since black will handle it.\nBlackened code looks the same for all authors, ensuring consistent code formatting within your project.\n\nThe format used by Black makes code review faster by producing the smaller diffs.\n\nBlack's output is always stable.\nFor a given block of code, a fixed version of black will always produce the same output.\nHowever, it should be noted that different versions of black will produce different outputs.\nBlack is configured here:\n\n- requirements-dev.txt, `L1 \u003chttps://github.com/flyingbird95/openapi-builder/blob/master/requirements-dev.txt#L1\u003e`__\n- .pre-commit-config.yaml, `L14 \u003chttps://github.com/flyingbird95/openapi-builder/blob/master/.pre-commit-config.yaml#L14\u003e`__,\n  `L28 \u003chttps://github.com/flyingbird95/openapi-builder/blob/master/.pre-commit-config.yaml#L28\u003e`__, and\n  `L47 \u003chttps://github.com/flyingbird95/openapi-builder/blob/master/.pre-commit-config.yaml#L47\u003e`__\n\n.. _black: https://github.com/psf/black\n\n\npre-commit\n~~~~~~~~~~\n\nThis repository comes with a pre-commit_ stack.\nThis is a set of git hooks which are executed every time a commit is made.\nThe hooks catch errors as they occur, and will automatically fix some of these errors.\n\nTo set up the pre-commit hooks, run the following code from within the repo directory::\n\n    pip install -r requirements-dev.txt\n    pre-commit install\n\nWhenever trying to commit code which is flagged by the pre-commit hooks, the commit will not go through.\nSome of the pre-commit hooks (such as black_, isort_) will automatically modify the code to fix the issues.\nWhen this happens, you'll have to stage the changes made by the commit hooks and then commit again.\nOther pre-commit hooks will not modify the code and will just tell you about issues which you'll then have to manually fix.\n\nTo run the pre-commit stack on all the files at any time::\n\n    pre-commit run --all-files\n\nTo force a commit to go through without passing the pre-commit hooks use the ``--no-verify`` flag::\n\n    git commit --no-verify\n\nThe pre-commit stack which comes with the template is highly opinionated, and includes the following operations:\n\n- Code is reformatted to use the black_ style.\n  Any code inside docstrings will be formatted to black using blackendocs_.\n  All code cells in Jupyter notebooks are also formatted to black using black_nbconvert_.\n\n- All Jupyter notebooks are cleared using nbstripout_.\n\n- Imports are automatically sorted using isort_.\n\n- flake8_ is run to check for conformity to the python style guide PEP-8_, along with several other formatting issues.\n\n- setup-cfg-fmt_ is used to format any setup.cfg files.\n\n- Several `hooks from pre-commit \u003cpre-commit-hooks_\u003e`_ are 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.\n  JSON files are also prettified automatically to have standardised indentation.\n  Entries in requirements.txt files are automatically sorted alphabetically.\n\n- Several `hooks from pre-commit specific to python \u003cpre-commit-py-hooks_\u003e`_ are used to screen for rST formatting issues, and ensure noqa flags always specify an error code to ignore.\n\nOnce it is set up, the pre-commit stack will run locally on every commit.\nThe 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.\n\n.. _black_nbconvert: https://github.com/dfm/black_nbconvert\n.. _blackendocs: https://github.com/asottile/blacken-docs\n.. _flake8: https://gitlab.com/pycqa/flake8\n.. _isort: https://github.com/timothycrosley/isort\n.. _nbstripout: https://github.com/kynan/nbstripout\n.. _PEP-8: https://www.python.org/dev/peps/pep-0008/\n.. _pre-commit: https://pre-commit.com/\n.. _pre-commit-hooks: https://github.com/pre-commit/pre-commit-hooks\n.. _pre-commit-py-hooks: https://github.com/pre-commit/pygrep-hooks\n.. _setup-cfg-fmt: https://github.com/asottile/setup-cfg-fmt\n\n\nAutomated documentation\n~~~~~~~~~~~~~~~~~~~~~~~\n\nThe script ``docs/conf.py`` is based on the Sphinx_ default configuration.\nIt is set up to work well out of the box, with several features added in.\n\nGitHub Pages\n^^^^^^^^^^^^\n\nDocumentation is deployed to `GitHub Pages`_ and is available at https://flyingbird95.github.io/openapi-builder/.\n\nThe gh-pages documentation is refreshed every time there is a push to the master branch.\n\nNote that only one copy of the documentation is served (the latest version).\n\n.. _GitHub Pages: https://pages.github.com/\n\nBuilding locally\n^^^^^^^^^^^^^^^^\n\nThe web documentation can be built locally with::\n\n   pip install -r requirements-docs.txt\n   make -C docs html\n\nAnd view the documentation like so::\n\n   sensible-browser docs/_build/html/index.html\n\nOr build the pdf documentation::\n\n   make -C docs latexpdf\n\nOn Windows, this becomes::\n\n    cd docs\n    make html\n    make latexpdf\n    cd ..\n\nOther documentation features\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n- The README.rst will become part of the generated documentation (via a link file ``docs/source/readme.rst``).\n  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.\n\n- The docstrings in all modules, functions, classes and methods will be used to build a set of API documentation using autodoc_.\n  Our ``docs/conf.py`` is also set up to automatically call autodoc whenever it is run, and the output files which it generates are on the gitignore list.\n  This means it will automatically generate a fresh API description which exactly matches the current docstrings every time the documentation is generated.\n\n- Docstrings can be formatted in plain reST_, or using the `numpy format`_ (recommended), or `Google format`_.\n  Support for numpy and Google formats is through the napoleon_ extension (which is enabled by default).\n\n- The reference functions in the python core and common packages and they will automatically be hyperlinked to the appropriate documentation in the documentation.\n  This is done using intersphinx_ mappings, which can be seen at the bottom of the ``docs/conf.py`` file.\n\n- The documentation theme is sphinx-book-theme_.\n  Alternative themes can be found at sphinx-themes.org_, sphinxthemes.com_, and writethedocs_.\n\n.. _autodoc: http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html\n.. _Google format: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google\n.. _intersphinx: http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html\n.. _napoleon: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html\n.. _numpy format: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy-style-python-docstrings\n.. _Sphinx: https://www.sphinx-doc.org/\n.. _sphinx-book-theme: https://sphinx-book-theme.readthedocs.io/\n.. _sphinx-themes.org: https://sphinx-themes.org\n.. _sphinxthemes.com: https://sphinxthemes.com/\n.. _reST: http://docutils.sourceforge.net/rst.html\n.. _writethedocs: https://www.writethedocs.org/guide/tools/sphinx-themes/\n\n\nConsolidated metadata\n~~~~~~~~~~~~~~~~~~~~~\n\nPackage metadata is consolidated into one place, the file ``openapi_builder/__meta__.py``.\nThis is done to only write the metadata once in this centralised location, and everything else (packaging, documentation, etc) picks it up from there.\nThis is similar to `single-sourcing the package version`_, but for all metadata.\n\nThis information is available to end-users with ``import openapi_builder; print(openapi_builder.__meta__)``.\nThe version information is also accessible at ``openapi_builder.__version__``, as per PEP-396_.\n\n.. _PEP-396: https://www.python.org/dev/peps/pep-0396/#specification\n.. _single-sourcing the package version: https://packaging.python.org/guides/single-sourcing-package-version/\n\n\nsetup.py\n~~~~~~~~\n\nThe ``setup.py`` script is used to build and install the package.\n\nThe package can be installed from source with::\n\n    pip install .\n\nor alternatively with::\n\n    python setup.py install\n\nBut do remember that as a developer, the package should be installed in editable mode, using either::\n\n    pip install --editable .\n\nor::\n\n    python setup.py develop\n\nwhich will mean changes to the source will affect the installed package immediately without having to reinstall it.\n\nBy default, when the package is installed only the main requirements, listed in ``requirements.txt`` will be installed with it.\nRequirements listed in ``requirements-dev.txt``, ``requirements-docs.txt``, and ``requirements-test.txt`` are optional extras.\nThe ``setup.py`` script is configured to include these as extras named ``dev``, ``docs``, and ``test``.\nThey can be installed along with::\n\n    pip install .[dev]\n\netc.\nAny additional files named ``requirements-EXTRANAME.txt`` will also be collected automatically and made available with the corresponding name ``EXTRANAME``.\nAnother extra named ``all`` captures all of these optional dependencies.\n\nThe README file is automatically included in the metadata when setup.py build wheels for PyPI.\nThe rest of the metadata comes from ``openapi_builder/__meta__.py``.\n\nOur template setup.py file is based on the `example from setuptools documentation \u003csetuptools-setup.py_\u003e`_, and the comprehensive example from `Kenneth Reitz \u003ckennethreitz/setup.py_\u003e`_ (released under `MIT License \u003chttps://github.com/kennethreitz/setup.py/blob/master/LICENSE\u003e`__), with further features added.\n\n.. _kennethreitz/setup.py: https://github.com/kennethreitz/setup.py\n.. _setuptools-setup.py: https://setuptools.readthedocs.io/en/latest/setuptools.html#basic-use\n\n\nGitHub Actions Workflows\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nGitHub features the ability to run various workflows whenever code is pushed to the repo or a pull request is opened.\nThis 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.\nIt is also useful to ensure that style guides are adhered to\n\nFive workflows are included:\n\ndocs\n    The docs workflow ensures the documentation builds correctly, and presents any errors and warnings nicely as annotations.\n    The available html documentation is automatically deployed to the gh-pages branch and https://flyingbird95.github.io/openapi-builder/.\n\npre-commit\n    Runs the pre-commit stack.\n    Ensures all contributions are compliant, even if a contributor has not set up pre-commit on their local machine.\n\nlint\n    Checks the code uses the black_ style and tests for flake8_ errors.\n    Note that the lint workflow is superfluous, due to the pre-commit hooks.\n\ntest\n    Runs the pytest, and pushes coverage reports to Codecov_.\n\nrelease candidate tests\n    The release candidate tests workflow runs the unit tests on more Python versions and operating systems than the regular test workflow.\n    This runs on all tags, plus pushes and PRs to branches named like \"v1.2.x\", etc.\n    Wheels are built for all the tested systems, and stored as artifacts for convenience when shipping a new distribution.\n\nWhen the ``publish`` job is enabled on the release candidate tests workflow, it can also push built release candidates to the `Test PyPI \u003ctestpypi_\u003e`_ server.\n\n.. _Codecov: https://codecov.io/\n.. _ci-packaging: https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/\n.. _github-secrets: https://docs.github.com/en/actions/reference/encrypted-secrets\n.. _pypi-api-token: https://pypi.org/help/#apitoken\n.. _pypi-publish: https://github.com/pypa/gh-action-pypi-publish\n.. _testpypi: https://test.pypi.org/\n\n\n\n.. |GHA tests| image:: https://github.com/flyingbird95/openapi-builder/workflows/tests/badge.svg\n   :target: https://github.com/flyingbird95/openapi-builder/actions?query=workflow%3Atests\n   :alt: GHA Status\n.. |Documentation| image:: https://github.com/flyingbird95/openapi-builder/workflows/docs/badge.svg\n   :target: https://flyingbird95.github.io/openapi-builder/index.html\n   :alt: Documentation\n.. |Codecov report| image:: https://codecov.io/github/flyingbird95/openapi-builder/coverage.svg?branch=master\n   :target: https://codecov.io/github/flyingbird95/openapi-builder?branch=master\n   :alt: Coverage\n.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white\n   :target: https://github.com/pre-commit/pre-commit\n   :alt: pre-commit\n.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n   :target: https://github.com/psf/black\n   :alt: black\n.. |pypi| image:: https://badge.fury.io/py/openapi-builder.svg\n   :target: https://badge.fury.io/py/openapi-builder\n   :alt: PyPI\n.. |downloads| image:: http://pepy.tech/badge/openapi-builder\n   :target: https://pepy.tech/project/openapi-builder\n   :alt: Downloads\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFlyingBird95%2Fopenapi-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFlyingBird95%2Fopenapi-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFlyingBird95%2Fopenapi-builder/lists"}