{"id":13468660,"url":"https://github.com/marshmallow-code/apispec","last_synced_at":"2025-05-16T01:04:05.315Z","repository":{"id":22083649,"uuid":"25413181","full_name":"marshmallow-code/apispec","owner":"marshmallow-code","description":"A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification)..","archived":false,"fork":false,"pushed_at":"2025-05-06T20:09:16.000Z","size":2020,"stargazers_count":1195,"open_issues_count":32,"forks_count":177,"subscribers_count":22,"default_branch":"dev","last_synced_at":"2025-05-06T21:24:25.360Z","etag":null,"topics":["api","documentation","flask","http-api","json-schema","marshmallow","openapi","openapi-specification","openapi2","openapi3","pluggable","python","rest-api","swagger"],"latest_commit_sha":null,"homepage":"https://apispec.readthedocs.io/","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/marshmallow-code.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"marshmallow","tidelift":"pypi/apispec"}},"created_at":"2014-10-18T23:48:49.000Z","updated_at":"2025-05-06T20:09:18.000Z","dependencies_parsed_at":"2023-01-13T21:50:36.262Z","dependency_job_id":"93378c40-9f6c-4ac4-be07-8da303121caf","html_url":"https://github.com/marshmallow-code/apispec","commit_stats":{"total_commits":1404,"total_committers":93,"mean_commits":"15.096774193548388","dds":0.7029914529914529,"last_synced_commit":"6583194325b5cd2033537d34d58cbf6ce2b99d2b"},"previous_names":["marshmallow-code/smore"],"tags_count":122,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marshmallow-code%2Fapispec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marshmallow-code%2Fapispec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marshmallow-code%2Fapispec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marshmallow-code%2Fapispec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marshmallow-code","download_url":"https://codeload.github.com/marshmallow-code/apispec/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252874821,"owners_count":21817912,"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","documentation","flask","http-api","json-schema","marshmallow","openapi","openapi-specification","openapi2","openapi3","pluggable","python","rest-api","swagger"],"created_at":"2024-07-31T15:01:16.025Z","updated_at":"2025-05-07T21:37:08.612Z","avatar_url":"https://github.com/marshmallow-code.png","language":"Python","readme":"*******\napispec\n*******\n\n|pypi| |build-status| |docs| |marshmallow-support| |openapi|\n\n.. |pypi| image:: https://badgen.net/pypi/v/apispec\n    :target: https://pypi.org/project/apispec/\n    :alt: PyPI package\n\n.. |build-status| image:: https://github.com/marshmallow-code/apispec/actions/workflows/build-release.yml/badge.svg\n    :target: https://github.com/marshmallow-code/webargs/actions/workflows/build-release.yml\n    :alt: Build status\n\n.. |docs| image:: https://readthedocs.org/projects/apispec/badge/\n   :target: https://apispec.readthedocs.io/\n   :alt: Documentation\n\n.. |marshmallow-support| image:: https://badgen.net/badge/marshmallow/3,4?list=1\n    :target: https://marshmallow.readthedocs.io/en/latest/upgrading.html\n    :alt: marshmallow 3|4 compatible\n\n.. |openapi| image:: https://badgen.net/badge/OAS/2,3?list=1\u0026color=cyan\n    :target: https://github.com/OAI/OpenAPI-Specification\n    :alt: OpenAPI Specification 2/3 compatible\n\n\nA pluggable API specification generator. Currently supports the `OpenAPI Specification \u003chttps://github.com/OAI/OpenAPI-Specification\u003e`_ (f.k.a. the Swagger specification).\n\nFeatures\n========\n\n- Supports the OpenAPI Specification (versions 2 and 3)\n- Framework-agnostic\n- Built-in support for `marshmallow \u003chttps://marshmallow.readthedocs.io/\u003e`_\n- Utilities for parsing docstrings\n\nInstallation\n============\n\n::\n\n    $ pip install -U apispec\n\nWhen using the marshmallow plugin, ensure a compatible marshmallow version is used: ::\n\n    $ pip install -U apispec[marshmallow]\n\nExample Application\n===================\n\n.. code-block:: python\n\n    from apispec import APISpec\n    from apispec.ext.marshmallow import MarshmallowPlugin\n    from apispec_webframeworks.flask import FlaskPlugin\n    from flask import Flask\n    from marshmallow import Schema, fields\n\n\n    # Create an APISpec\n    spec = APISpec(\n        title=\"Swagger Petstore\",\n        version=\"1.0.0\",\n        openapi_version=\"3.0.2\",\n        plugins=[FlaskPlugin(), MarshmallowPlugin()],\n    )\n\n\n    # Optional marshmallow support\n    class CategorySchema(Schema):\n        id = fields.Int()\n        name = fields.Str(required=True)\n\n\n    class PetSchema(Schema):\n        category = fields.List(fields.Nested(CategorySchema))\n        name = fields.Str()\n\n\n    # Optional security scheme support\n    api_key_scheme = {\"type\": \"apiKey\", \"in\": \"header\", \"name\": \"X-API-Key\"}\n    spec.components.security_scheme(\"ApiKeyAuth\", api_key_scheme)\n\n\n    # Optional Flask support\n    app = Flask(__name__)\n\n\n    @app.route(\"/random\")\n    def random_pet():\n        \"\"\"A cute furry animal endpoint.\n        ---\n        get:\n          description: Get a random pet\n          security:\n            - ApiKeyAuth: []\n          responses:\n            200:\n              content:\n                application/json:\n                  schema: PetSchema\n        \"\"\"\n        pet = get_random_pet()\n        return PetSchema().dump(pet)\n\n\n    # Register the path and the entities within it\n    with app.test_request_context():\n        spec.path(view=random_pet)\n\n\nGenerated OpenAPI Spec\n----------------------\n\n.. code-block:: python\n\n    import json\n\n    print(json.dumps(spec.to_dict(), indent=2))\n    # {\n    #   \"paths\": {\n    #     \"/random\": {\n    #       \"get\": {\n    #         \"description\": \"Get a random pet\",\n    #         \"security\": [\n    #           {\n    #             \"ApiKeyAuth\": []\n    #           }\n    #         ],\n    #         \"responses\": {\n    #           \"200\": {\n    #             \"content\": {\n    #               \"application/json\": {\n    #                 \"schema\": {\n    #                   \"$ref\": \"#/components/schemas/Pet\"\n    #                 }\n    #               }\n    #             }\n    #           }\n    #         }\n    #       }\n    #     }\n    #   },\n    #   \"tags\": [],\n    #   \"info\": {\n    #     \"title\": \"Swagger Petstore\",\n    #     \"version\": \"1.0.0\"\n    #   },\n    #   \"openapi\": \"3.0.2\",\n    #   \"components\": {\n    #     \"parameters\": {},\n    #     \"responses\": {},\n    #     \"schemas\": {\n    #       \"Category\": {\n    #         \"type\": \"object\",\n    #         \"properties\": {\n    #           \"name\": {\n    #             \"type\": \"string\"\n    #           },\n    #           \"id\": {\n    #             \"type\": \"integer\",\n    #             \"format\": \"int32\"\n    #           }\n    #         },\n    #         \"required\": [\n    #           \"name\"\n    #         ]\n    #       },\n    #       \"Pet\": {\n    #         \"type\": \"object\",\n    #         \"properties\": {\n    #           \"name\": {\n    #             \"type\": \"string\"\n    #           },\n    #           \"category\": {\n    #             \"type\": \"array\",\n    #             \"items\": {\n    #               \"$ref\": \"#/components/schemas/Category\"\n    #             }\n    #           }\n    #         }\n    #       }\n    #       \"securitySchemes\": {\n    #          \"ApiKeyAuth\": {\n    #            \"type\": \"apiKey\",\n    #            \"in\": \"header\",\n    #            \"name\": \"X-API-Key\"\n    #         }\n    #       }\n    #     }\n    #   }\n    # }\n\n    print(spec.to_yaml())\n    # components:\n    #   parameters: {}\n    #   responses: {}\n    #   schemas:\n    #     Category:\n    #       properties:\n    #         id: {format: int32, type: integer}\n    #         name: {type: string}\n    #       required: [name]\n    #       type: object\n    #     Pet:\n    #       properties:\n    #         category:\n    #           items: {$ref: '#/components/schemas/Category'}\n    #           type: array\n    #         name: {type: string}\n    #       type: object\n    #   securitySchemes:\n    #     ApiKeyAuth:\n    #       in: header\n    #       name: X-API-KEY\n    #       type: apiKey\n    # info: {title: Swagger Petstore, version: 1.0.0}\n    # openapi: 3.0.2\n    # paths:\n    #   /random:\n    #     get:\n    #       description: Get a random pet\n    #       responses:\n    #         200:\n    #           content:\n    #             application/json:\n    #               schema: {$ref: '#/components/schemas/Pet'}\n    #       security:\n    #       - ApiKeyAuth: []\n    # tags: []\n\n\nDocumentation\n=============\n\nDocumentation is available at https://apispec.readthedocs.io/ .\n\nEcosystem\n=========\n\nA list of apispec-related libraries can be found at the GitHub wiki here:\n\nhttps://github.com/marshmallow-code/apispec/wiki/Ecosystem\n\nSupport apispec\n===============\n\napispec is maintained by a group of\n`volunteers \u003chttps://apispec.readthedocs.io/en/latest/authors.html\u003e`_.\nIf you'd like to support the future of the project, please consider\ncontributing to our Open Collective:\n\n.. image:: https://opencollective.com/marshmallow/donate/button.png\n    :target: https://opencollective.com/marshmallow\n    :width: 200\n    :alt: Donate to our collective\n\nProfessional Support\n====================\n\nProfessionally-supported apispec is available through the\n`Tidelift Subscription \u003chttps://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec\u0026utm_medium=referral\u0026utm_campaign=readme\u003e`_.\n\nTidelift gives software development teams a single source for purchasing and maintaining their software,\nwith professional-grade assurances from the experts who know it best,\nwhile seamlessly integrating with existing tools. [`Get professional support`_]\n\n.. _`Get professional support`: https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec\u0026utm_medium=referral\u0026utm_campaign=readme\n\n.. image:: https://user-images.githubusercontent.com/2379650/45126032-50b69880-b13f-11e8-9c2c-abd16c433495.png\n    :target: https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec\u0026utm_medium=referral\u0026utm_campaign=readme\n    :alt: Get supported apispec with Tidelift\n\nSecurity Contact Information\n============================\n\nTo report a security vulnerability, please use the\n`Tidelift security contact \u003chttps://tidelift.com/security\u003e`_.\nTidelift will coordinate the fix and disclosure.\n\nProject Links\n=============\n\n- Docs: https://apispec.readthedocs.io/\n- Changelog: https://apispec.readthedocs.io/en/latest/changelog.html\n- Contributing Guidelines: https://apispec.readthedocs.io/en/latest/contributing.html\n- PyPI: https://pypi.python.org/pypi/apispec\n- Issues: https://github.com/marshmallow-code/apispec/issues\n\n\nLicense\n=======\n\nMIT licensed. See the bundled `LICENSE \u003chttps://github.com/marshmallow-code/apispec/blob/dev/LICENSE\u003e`_ file for more details.\n","funding_links":["https://opencollective.com/marshmallow","https://tidelift.com/funding/github/pypi/apispec","https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec\u0026utm_medium=referral\u0026utm_campaign=readme","https://tidelift.com/security"],"categories":["Python","OpenAPI Utilities","api","\u003ca name=\"Python\"\u003e\u003c/a\u003ePython","API-First Tools"],"sub_categories":["Code Generation"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarshmallow-code%2Fapispec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarshmallow-code%2Fapispec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarshmallow-code%2Fapispec/lists"}