{"id":21566065,"url":"https://github.com/kulgan/flaskdoc","last_synced_at":"2025-06-11T05:34:29.968Z","repository":{"id":49681980,"uuid":"208150427","full_name":"kulgan/flaskdoc","owner":"kulgan","description":"Flask OpenAPI annotations","archived":false,"fork":false,"pushed_at":"2021-06-14T12:31:53.000Z","size":7746,"stargazers_count":4,"open_issues_count":7,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-05-10T22:48:38.622Z","etag":null,"topics":["api","api-docs","docs","documentation","documentation-tool","flask","models","openapi","openapi3","swagger"],"latest_commit_sha":null,"homepage":"https://flaskdoc.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kulgan.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-09-12T21:35:27.000Z","updated_at":"2022-06-21T18:40:09.000Z","dependencies_parsed_at":"2022-09-07T23:51:58.226Z","dependency_job_id":null,"html_url":"https://github.com/kulgan/flaskdoc","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulgan%2Fflaskdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulgan%2Fflaskdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulgan%2Fflaskdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulgan%2Fflaskdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kulgan","download_url":"https://codeload.github.com/kulgan/flaskdoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulgan%2Fflaskdoc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259208543,"owners_count":22821959,"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":["api","api-docs","docs","documentation","documentation-tool","flask","models","openapi","openapi3","swagger"],"created_at":"2024-11-24T10:23:28.417Z","updated_at":"2025-06-11T05:34:29.929Z","avatar_url":"https://github.com/kulgan.png","language":"Python","readme":"flaskdoc\n========\n\n|PyPi version| |Python version| |ci| |docs| |license| |coverage| |code quality|\n\nFlaskDoc allows developers to programmatically compose openapi specifications for flask endpoints as a part of code\nwithout needing to write a separate yaml file, and it comes with SwaggerUI embedded. Its main focus is on documentation\nwhich frees developers to focus on getting their services coded.\n\nWhy flaskdoc\n------------\n\n* Focus only on documentation and not introduce some fancy new way of using flask.\n* Easily add to existing code without needing to refactor of change the way the code has been written\n* Little or no learning curve, as long as a developer is comforatble using flask developers, they can use flaskdoc.\n  to learn quickly and not distract So developers focus on writing code\n* SwaggerUI integration for quickly testing and iterating through versions\n* Automatic data model to JSON Schema transformation that allows for finer grain configuration\n\n\nGetting Started\n---------------\nVisit `documentation \u003chttps://flaskdoc.readthedocs.io\u003e`_ page for more details.\n\nInstall\n\"\"\"\"\"\"\"\nfrom pypi\n\n.. code-block::\n\n    $ pip install flaskdoc\n\nfrom github\n\n.. code-block::\n\n    $ pip install https://github.com/kulgan/flaskdoc/tarball/master\n\nTo run examples you will need to install the dev extension\n\n.. code-block::\n\n    $ pip install flaskdoc[dev]\n\nRegister OpenAPI\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\nAdd top level openapi objects like `Info \u003chttps://swagger.io/specification/#info-object\u003e`_,\n`Contact \u003chttps://swagger.io/specification/#contact-object\u003e`_, `License \u003chttps://swagger.io/specification/#license-object\u003e`_ etc\n\n.. code-block:: python\n\n    import flask\n    from flaskdoc import register_openapi, swagger\n\n    app = flask.Flask()\n    # initialize app, add all the blueprints you care about\n\n    # Create top level OpenAPI objects\n    # the info object\n    info = swagger.Info(\n        title=\"Test\",\n        version=\"1.2.2\",\n        contact=swagger.Contact(\n            name=\"Rowland\", email=\"r.ogwara@gmail.com\", url=\"https://github.com/kulgan\"\n        ),\n        license=swagger.License(name=\"Apache 2.0\", url=\"https://www.example.com/license\"),\n    )\n\n    # servers names and variables if necessary\n    servers = [swagger.Server(url=\"http://localhost:15172\")]\n\n    # top level tags\n    tags = [\n        swagger.Tag(name=\"admin\", description=\"Secured Admin-Only calls\"),\n        swagger.Tag(name=\"developers\", description=\"Operations available to regular developers\"),\n    ]\n\n    security_schemes = {\n        \"api_key\": swagger.ApiKeySecurityScheme(name=\"api_key\"),\n    }\n\n    # register spec\n    register_openapi(app, info=info, servers=servers, tags=tags, security=security_schemes)\n\nThis adds the following endpoints to your list\n\n* /docs\n* /docs/openapi.yaml\n* /docs/openapi.json\n\nStart Documenting\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\nNow start documenting you flask routes\n\nA simple post example\n\n.. code-block:: python\n\n    blp = flask.Blueprint(\"Dummy\", __name__, url_prefix=\"/v1\")\n    @swagger.POST(\n        tags=[\"administrator\"],\n        description=\"Posts an Echo\",\n        responses={\"201\": swagger.ResponseObject(description=\"OK\")},\n    )\n    @blp.route(\"/echo\", methods=[\"POST\"])\n    def post():\n        req = flask.request.get_json(force=True)\n        return flask.jsonify(req), 200\n\nA GET example with path parameter\n\n.. code-block:: python\n\n    blp = flask.Blueprint(\"Dummy\", __name__, url_prefix=\"/v1\")\n\n    @swagger.GET(\n        tags=[\"getEcho\"],\n        operation_id=\"getEcho\",\n        parameters=[swagger.PathParameter(name=\"sample\", schema=str)],\n        description=\"Retrieve echos wit Get\",\n        responses={\n            \"200\": swagger.ResponseObject(\n                description=\"Success\", content=jo.PlainText(schema=jo.Email()),\n            )\n        },\n    )\n    @blp.route(\"/echo/\u003cstring:sample\u003e\", methods=[\"GET\"])\n    def echo(sample: str):\n        \"\"\"\n        Sample GET request\n        Returns: Echos back whatever was sent\n\n        \"\"\"\n        return sample\n\nRun your app and visit `/docs` to see the generated openapi specs\n\nRunning Examples\n================\n\nTwo example projects are currently provided\n\n* `inventory \u003csrc/flaskdoc/examples/inventory.py\u003e`_\n* `petstore \u003csrc/flaskdoc/examples/petstore.py\u003e`_ source `OpenAPI Petstore \u003chttps://petstore.swagger.io\u003e`_\n* `link-example \u003csrc/flaskdoc/examples/link_example/v0.py\u003e`_ - source `OpenAPI link example \u003chttps://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/link-example.json\u003e`_\n* `api-with-example \u003csrc/flaskdoc/examples/api_with_example.py\u003e`_ - source `OpenAPI api_with_examples \u003chttps://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/api-with-examples.json\u003e`_\n\nTo run\n\n.. code-block:: bash\n\n    $ pip install flaskdoc[dev]\n    $ flaskdoc start -n petstore\n\nContributing\n------------\n\nDon't hesitate to create a `Github issue \u003chttps://github.com/kulgan/flaskdoc/issues\u003e`__ for any bugs or suggestions\n\n.. |ci| image:: https://github.com/kulgan/flaskdoc/workflows/ci/badge.svg\n    :target: https://github.com/kulgan/flaskdoc/\n    :alt: build\n\n.. |PyPi version| image:: https://img.shields.io/pypi/v/flaskdoc.svg\n    :target: https://pypi.org/project/flaskdoc/\n    :alt: PyPi downloads\n\n.. |Python version| image:: https://img.shields.io/pypi/pyversions/flaskdoc.svg\n    :target: https://pypi.org/project/flaskdoc/\n    :alt: Python versions\n\n.. |license| image:: https://img.shields.io/pypi/l/flaskdoc.svg\n    :target: https://pypi.org/project/flaskdoc/\n    :alt: license\n.. |docs| image:: https://readthedocs.org/projects/flaskdoc/badge/?version=latest\n    :target: https://flaskdoc.readthedocs.io/en/latest/?badge=latest\n    :alt: Documentation Status\n\n.. |code quality| image:: https://app.codacy.com/project/badge/Grade/2dafebf021354a42aa62b11d6ab42654\n    :target: https://www.codacy.com/manual/kulgan/flaskdoc?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=kulgan/flaskdoc\u0026amp;utm_campaign=Badge_Grade\n    :alt: Code Quality\n\n.. |coverage| image:: https://app.codacy.com/project/badge/Coverage/2dafebf021354a42aa62b11d6ab42654\n    :target: https://www.codacy.com/manual/kulgan/flaskdoc?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=kulgan/flaskdoc\u0026amp;utm_campaign=Badge_Coverage\n    :alt: Coverage\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkulgan%2Fflaskdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkulgan%2Fflaskdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkulgan%2Fflaskdoc/lists"}