{"id":13493180,"url":"https://github.com/Fatal1ty/openapify","last_synced_at":"2025-03-28T11:31:56.350Z","repository":{"id":152713537,"uuid":"625681832","full_name":"Fatal1ty/openapify","owner":"Fatal1ty","description":"Framework agnostic OpenAPI Specification generation for code lovers","archived":false,"fork":false,"pushed_at":"2024-11-25T12:02:20.000Z","size":59,"stargazers_count":25,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T01:51:10.930Z","etag":null,"topics":["api","dataclasses","documentation","http-api","json-schema","jsonschema","openapi","openapi-generator","openapi-specification","openapi3","openapi31","python","rest-api","swagger"],"latest_commit_sha":null,"homepage":"","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/Fatal1ty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"custom":["https://coindrop.to/tikhonov_a"]}},"created_at":"2023-04-09T21:19:19.000Z","updated_at":"2025-03-21T06:41:10.000Z","dependencies_parsed_at":"2024-03-07T03:46:38.534Z","dependency_job_id":null,"html_url":"https://github.com/Fatal1ty/openapify","commit_stats":{"total_commits":86,"total_committers":1,"mean_commits":86.0,"dds":0.0,"last_synced_commit":"c8d968c7c9c8fd7d4888bd2ddbe18ffd1469f3ca"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fatal1ty%2Fopenapify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fatal1ty%2Fopenapify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fatal1ty%2Fopenapify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Fatal1ty%2Fopenapify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Fatal1ty","download_url":"https://codeload.github.com/Fatal1ty/openapify/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246021065,"owners_count":20710878,"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","dataclasses","documentation","http-api","json-schema","jsonschema","openapi","openapi-generator","openapi-specification","openapi3","openapi31","python","rest-api","swagger"],"created_at":"2024-07-31T19:01:12.963Z","updated_at":"2025-03-28T11:31:56.341Z","avatar_url":"https://github.com/Fatal1ty.png","language":"Python","readme":"# openapify\n\n###### Framework agnostic OpenAPI Specification generation for code lovers\n\n[![Build Status](https://github.com/Fatal1ty/openapify/workflows/tests/badge.svg)](https://github.com/Fatal1ty/openapify/actions)\n[![Latest Version](https://img.shields.io/pypi/v/openapify.svg)](https://pypi.python.org/pypi/openapify)\n[![Python Version](https://img.shields.io/pypi/pyversions/openapify.svg)](https://pypi.python.org/pypi/openapify)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n---\n\nThis library is designed for code-first people who don't want to bother diving\ninto the details\nof [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0), but who\ninstead want to use advantages of Python typing system, IDE code-completion and\nstatic type checkers to continuously build the API documentation and keep it\nalways up to date.\n\nOpenapify is based on the idea of applying decorators on route handlers. Any\nweb-framework has a routing system that let us link a route to a handler\n(a high-level function or a class method). By using decorators, we can add\ninformation about requests, responses and other details that will then be used\nto create an entire OpenAPI document.\n\n\u003e [!WARNING]\\\n\u003e This library is currently in pre-release stage and may have backward\n\u003e incompatible changes prior to version 1.0. Please use caution when using this\n\u003e library in production environments and be sure to thoroughly test any updates\n\u003e before upgrading to a new version.\n\nTable of contents\n--------------------------------------------------------------------------------\n\n* [Installation](#installation)\n* [Quickstart](#quickstart)\n* [Building the OpenAPI Document](#building-the-openapi-document)\n* [Integration with web-frameworks](#integration-with-web-frameworks)\n    * [aiohttp](#aiohttp)\n    * [Writing your own integration](#writing-your-own-integration)\n* [Decorators](#decorators)\n    * [Generic operation info](#generic-operation-info)\n    * [Request](#request)\n    * [Response](#response)\n    * [Security requirements](#security-requirements)\n* [Plugins](#plugins)\n  * [`schema_helper`](#schema_helper)\n  * [`media_type_helper`](#media_type_helper)\n\nInstallation\n--------------------------------------------------------------------------------\n\nUse pip to install:\n\n```shell\n$ pip install openapify\n```\n\nQuickstart\n--------------------------------------------------------------------------------\n\n\u003e [!NOTE]\\\n\u003e In the following example, we will intentionally demonstrate the process of\n\u003e creating an OpenAPI document without being tied to a specific web-framework.\n\u003e However, this process may be easier on a supported web-framework.\n\u003e See [Integration with web-frameworks](#integration-with-web-frameworks) for\n\u003e more info.\n\nLet's see how to build an OpenAPI document with openapify. Suppose we are\nwriting an app for a bookstore that return a list of new books. Here we have a\ndataclass model `Book` that would be used as a response model in a real-life\nscenario. A function `get_new_books` is our handler.\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Book:\n    title: str\n    author: str\n    year: int\n\ndef get_new_books(...):\n    ...\n```\n\nNow we want to say that our handler returns a json serialized list of books\nlimited by the optional `count` parameter. We use `request_schema`\nand `response_schema` decorators accordingly:\n\n```python\nfrom openapify import request_schema, response_schema\n\n@request_schema(query_params={\"count\": int})\n@response_schema(list[Book])\ndef get_new_books(...):\n    ...\n```\n\nAnd now we need to collect all the route definitions and pass them to the\n`build_spec` function. This function returns an object that has `to_yaml`\nmethod.\n\n```python\nfrom openapify import build_spec\nfrom openapify.core.models import RouteDef\n\nroutes = [RouteDef(\"/books\", \"get\", get_new_books)]\nspec = build_spec(routes)\nprint(spec.to_yaml())\n```\n\nAs a result, we will get the following OpenAPI document which can be rendered\nusing tools such as Swagger UI:\n\n```yaml\nopenapi: 3.1.0\ninfo:\n  title: API\n  version: 1.0.0\npaths:\n  /books:\n    get:\n      parameters:\n      - name: count\n        in: query\n        schema:\n          type: integer\n      responses:\n        '200':\n          description: OK\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  $ref: '#/components/schemas/Book'\ncomponents:\n  schemas:\n    Book:\n      type: object\n      title: Book\n      properties:\n        title:\n          type: string\n        author:\n          type: string\n        year:\n          type: integer\n      additionalProperties: false\n      required:\n      - title\n      - author\n      - year\n```\n\nBuilding the OpenAPI Document\n--------------------------------------------------------------------------------\nThe final goal of this library is to build\nthe [OpenAPI Document](https://spec.openapis.org/oas/v3.1.0#openapi-document)\nfor your web-application. This document consists of common information about\nthe application, such as a title and version, and specific information that\noutlines the functionalities of the API.\n\nSince openapify is now based\non [apispec](https://github.com/marshmallow-code/apispec) library, the OpenAPI\ndocument is presented by `APISpec` class for the convenience of using the\nexisting ecosystem of plugins. However, openapify has its own\nsubclass `OpenAPIDocument` which makes it easier to add some common fields,\nsuch as an array\nof [Server](https://spec.openapis.org/oas/v3.1.0#server-object) objects or\narray of\ncommon [Security Scheme](https://spec.openapis.org/oas/v3.1.0#security-scheme-object)\nobjects.\n\nTo build the document, there is `build_spec` function. The very basic document\ncan be created by calling it with an empty list of route definitions, leaving\nall the parameters with their default values.\n```python\nfrom openapify import build_spec\n\nprint(build_spec([]).to_yaml())\n```\n\nAs a result, we will get the following document:\n\n```yaml\nopenapi: 3.1.0\ninfo:\n  title: API\n  version: 1.0.0\npaths: {}\n```\n\nWe can change the common document attributes either by passing them\nto `build_spec`:\n\n```python\nfrom openapify import build_spec\nfrom openapify.core.openapi.models import HTTPSecurityScheme\n\nbuild_spec(\n    routes=[],\n    title=\"My Bookstore API\",\n    version=\"1.1.0\",\n    openapi_version=\"3.1.0\",\n    servers=[\"http://127.0.0.1\"],\n    security_schemes={\"basic_auth\": HTTPSecurityScheme()}\n)\n```\n\nor using a prepared `OpenAPIDocument` object:\n\n```python\nfrom openapify import OpenAPIDocument, build_spec\nfrom openapify.core.openapi.models import HTTPSecurityScheme\n\nspec = OpenAPIDocument(\n    title=\"My Bookstore API\",\n    version=\"1.1.0\",\n    openapi_version=\"3.1.0\",\n    servers=[\"http://127.0.0.1\"],\n    security_schemes={\"basic_auth\": HTTPSecurityScheme()},\n)\nbuild_spec([], spec)\n```\n\nTo add meaning to our document, we can\nadd [Path](https://spec.openapis.org/oas/v3.1.0#paths-object),\n[Component](https://spec.openapis.org/oas/v3.1.0#components-object)\nand other OpenAPI objects by applying [decorators](#decorators) on our route\nhandlers and constructing route definitions that will be passed to the builder.\nA single complete route definition presented by `RouteDef` class can look like\nthis:\n\n```python\nfrom openapify.core.models import RouteDef\nfrom openapify.core.openapi.models import Parameter, ParameterLocation\n\ndef get_book_by_id_handler(...):\n    ...\n\nRouteDef(\n    path=\"/book/{id}\",\n    method=\"get\",\n    handler=get_book_by_id_handler,\n    summary=\"Getting the book\",\n    description=\"Getting the book by id\",\n    parameters=[\n        Parameter(\n            name=\"id\",\n            location=ParameterLocation.PATH,\n            required=True,\n            schema={\"type\": \"integer\"},\n        )\n    ],\n    tags=[\"book\"],\n)\n```\n\nAs will be shown further, optional\narguments `summary`, `description`, `parameters` and `tags` can be overridden\nor extended by `operation_docs` and `request_schema` decorators.\n\nThe creating of these route definitions can be automated and adapted to a\nspecific web-framework, and openapify has built-in support for a few of them.\nSee [Integration with web-frameworks](#integration-with-web-frameworks) for\ndetails.\n\nIntegration with web-frameworks\n--------------------------------------------------------------------------------\n\nThere is built-in support for a few web-frameworks, which makes creating the\ndocumentation even easier and more fun. Any other frameworks can be integrated\nwith a little effort. If you are ready to take on this, you are very welcome to\ncreate a [pull request](https://github.com/Fatal1ty/openapify/pulls).\n\n### aiohttp\n\nThe documentation for [aiohttp](https://github.com/aio-libs/aiohttp)\nweb-application can be built in three ways:\n\n* Using an already existing [`aiohttp.web.Application`](https://docs.aiohttp.org/en/stable/web_reference.html#application) object\n* Using a set of [`aiohttp.web.RouteDef`](https://docs.aiohttp.org/en/stable/web_reference.html#aiohttp.web.RouteDef) objects\n* Using a set of objects implementing [`AioHttpRouteDef`](https://github.com/Fatal1ty/openapify/blob/2bbf2e99c06b31fa2f1465f2ebc118884ce2bb95/openapify/ext/web/aiohttp.py#L43-L46) protocol\n\nAll we need is to pass either an application, or a set of route defs to\nmodified `build_spec` function. See the example:\n```python\nfrom aiohttp import web\nfrom openapify import request_schema, response_schema\nfrom openapify.ext.web.aiohttp import build_spec\n\nroutes = web.RouteTableDef()\n\n@response_schema(str, media_type=\"text/plain\")\n@routes.post(\"/\")\nasync def hello(request):\n    return web.Response(text=\"Hello, world\")\n\napp = web.Application()\napp.add_routes(routes)\n\nprint(build_spec(app).to_yaml())\n```\nAs a result, we will get the following document:\n\n```yaml\nopenapi: 3.1.0\ninfo:\n  title: API\n  version: 1.0.0\npaths:\n  /:\n    post:\n      responses:\n        '200':\n          description: OK\n          content:\n            text/plain:\n              schema:\n                type: string\n```\n\n### Writing your own integration\n\n🚧 To be described\n\nDecorators\n--------------------------------------------------------------------------------\n\nOpenapify has several decorators that embed necessary specific information for\nlater use when building the OpenAPI document. In general, decorators will\ndefine the information that will be included in\nthe [Operation Object](https://spec.openapis.org/oas/v3.1.0#operation-object)\nwhich describes a single API operation on a path. We will look at what each\ndecorator parameter is responsible for and how it is reflected in the final\ndocument.\n\n### Generic operation info\n\nDecorator `operation_docs` adds generic information about the Operation object,\nwhich includes summary, description, tags, external documentation and\ndeprecation marker.\n\n```python\nfrom openapify import operation_docs\n```\n\n#### summary\n\nAn optional, string summary, intended to apply to the operation. This affects\nthe value of\nthe [`summary`](https://spec.openapis.org/oas/v3.1.0#operation-object) field of\nthe Operation object.\n\n| Possible types | Examples              |\n|----------------|-----------------------|\n| `str`          | `\"Getting new books\"` |\n\n#### description\n\nAn optional, string description, intended to apply to the\noperation. [CommonMark syntax](https://spec.commonmark.org) MAY be used for\nrich text representation. This affects the value of\nthe [`description`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object.\n\n| Possible types | Examples                    |\n|----------------|-----------------------------|\n| `str`          | `\"Returns a list of books\"` |\n\n#### tags\n\nA list of tags for API documentation control. Tags can be used for logical\ngrouping of operations by resources or any other qualifier. This affects the\nvalue of the [`tags`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object.\n\n| Possible types  | Examples   |\n|-----------------|------------|\n| `Sequence[str]` | `[\"book\"]` |\n\n#### operation_id\n\nUnique string used to identify the operation. This affects the\nvalue of\nthe [`operationId`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object.\n\n| Possible types | Examples   |\n|----------------|------------|\n| `str`          | `getBooks` |\n\n#### external_docs\n\nAdditional external documentation for the operation. It can be a single url or\n(url, description) pair. This affects the value of\nthe [`summary`](https://spec.openapis.org/oas/v3.1.0#operation-object) field of\nthe Operation object.\n\n| Possible types    | Examples                                                                  |\n|-------------------|---------------------------------------------------------------------------|\n| `str`             | `\"https://example.org/docs/books\"`                                        |\n| `Tuple[str, str]` | `(\"https://example.org/docs/books\", \"External documentation for /books\")` |\n\n#### deprecated\n\nDeclares the operation to be deprecated. Consumers SHOULD refrain from usage\nof the declared operation. Default value is false. This affects the value of\nthe [`deprecated`](https://spec.openapis.org/oas/v3.1.0#operation-object) field\nof the Operation object.\n\n| Possible types | Examples                       |\n|----------------|--------------------------------|\n| `bool`         | \u003ccode lang=\"python\"\u003eTrue\u003c/pre\u003e |\n\n### Request\n\nDecorator `request_schema` adds information about the operation requests.\nRequest can have a body, query parameters, headers and cookies.\n\n```python\nfrom openapify import request_schema\n```\n\n#### body\n\nA request body can be described entirely by one `body` parameter of type `Body`\nor partially by separate `body_*` parameters (see below).\n\nIn the first case it is `openapify.core.models.Body` object that has all the\nseparate `body_*` parameters inside. This affects the value of\nthe [`requestBody`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object.\n\nIn the second case it is the request body Python data type for which the JSON\nSchema will be built. This affects the value of\nthe [`requestBody`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`schema`](https://spec.openapis.org/oas/v3.1.0#media-type-object) field of\nMedia Type object inside\nthe value\nof [`content`](https://spec.openapis.org/oas/v3.1.0#request-body-object) field\nof Request Body object.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003ePossible types\u003c/th\u003e\n\u003cth\u003eExamples\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eType\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\nBook\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eBody\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\nBody(\n    value_type=Book,\n    media_type=\"application/json\",\n    required=True,\n    description=\"A book\",\n    example={\n        \"title\": \"Anna Karenina\",\n        \"author\": \"Leo Tolstoy\",\n        \"year\": 1877,\n    },\n)\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### media_type\n\nA media type\nor [media type range](https://www.rfc-editor.org/rfc/rfc7231#appendix-D) of the\nrequest body. This affects the value of\nthe [`requestBody`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe key\nof [`content`](https://spec.openapis.org/oas/v3.1.0#request-body-object) field\nof Request Body object.\n\nThe default value is `\"application/json\"`.\n\n| Possible types | Examples            |\n|----------------|---------------------|\n| `str`          | `\"application/xml\"` |\n\n#### body_required\n\nDetermines if the request body is required in the request. Defaults to false.\nThis affects the value of\nthe [`requestBody`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`required`](https://spec.openapis.org/oas/v3.1.0#request-body-object)\nfield of Request Body object.\n\n| Possible types | Examples |\n|----------------|----------|\n| `bool`         | `True`   |\n\n#### body_description\n\nA brief description of the request body. This could contain examples of\nuse. [CommonMark syntax](https://spec.commonmark.org) MAY be used for rich text\nrepresentation. This affects the value of\nthe [`requestBody`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`description`](https://spec.openapis.org/oas/v3.1.0#request-body-object)\nfield of Request Body object.\n\n| Possible types | Examples   |\n|----------------|------------|\n| `str`          | `\"A book\"` |\n\n#### body_example\n\nExample of the request body. The example object SHOULD be in the correct format\nas specified by the media type. This affects the value of\nthe [`requestBody`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`example`](https://spec.openapis.org/oas/v3.1.0#media-type-object) field\nof\nMedia Type object inside\nthe value\nof [`content`](https://spec.openapis.org/oas/v3.1.0#request-body-object) field\nof Request Body object.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003ePossible types\u003c/th\u003e\n\u003cth\u003eExamples\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eAny\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\n    \"title\": \"Anna Karenina\",\n    \"author\": \"Leo Tolstoy\",\n    \"year\": 1877,\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### body_examples\n\nExamples of the request body. Each example object SHOULD match the media type\nand specified schema if present. This affects the value of\nthe [`requestBody`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`examples`](https://spec.openapis.org/oas/v3.1.0#media-type-object) field\nof\nMedia Type object inside\nthe value\nof [`content`](https://spec.openapis.org/oas/v3.1.0#request-body-object) field\nof Request Body object.\n\nThe values of this dictionary could be either examples themselves,\nor `openapify.core.openapi.models.Example` objects. In the latter case,\nextended information about examples, such as a summary and description, can be\nadded to the [Example](https://spec.openapis.org/oas/v3.1.0#example-object)\nobject.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003ePossible types\u003c/th\u003e\n\u003cth\u003eExamples\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, Any]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\n    \"Anna Karenina\": {\n        \"title\": \"Anna Karenina\",\n        \"author\": \"Leo Tolstoy\",\n        \"year\": 1877,\n    }\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, Example]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\n    \"Anna Karenina\": Example(\n        value={\n            \"title\": \"Anna Karenina\",\n            \"author\": \"Leo Tolstoy\",\n            \"year\": 1877,\n        },\n        summary=\"The book 'Anna Karenina'\",\n    )\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### query_params\n\nDictionary of query parameters applicable for the operation, where the key is\nthe parameter name and the value can be either a Python data type or\na `QueryParam` object.\n\nIn the first case it is the Python data type for the query parameter for which\nthe JSON Schema will be built. This affects the value of\nthe [`parameters`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`schema`](https://spec.openapis.org/oas/v3.1.0#parameter-object) field of\nParameter object.\n\nIn the second case it is `openapify.core.models.QueryParam` object that can\nhave extended information about the parameter, such as a default value,\ndeprecation marker, examples etc.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003ePossible types\u003c/th\u003e\n\u003cth\u003eExamples\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, Type]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\"count\": int}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, QueryParam]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\n    \"count\": QueryParam(\n        value_type=int,\n        default=10,\n        required=True,\n        description=\"Limits the number of books returned\",\n        deprecated=False,\n        allowEmptyValue=False,\n        example=42,\n    )\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### headers\n\nDictionary of request headers applicable for the operation, where the key is\nthe header name and the value can be either a string or a `Header` object.\n\nIn the first case it is the header description. This affects the value of\nthe [`parameters`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`description`](https://spec.openapis.org/oas/v3.1.0#parameter-object)\nfield of Parameter object.\n\nIn the second case it is `openapify.core.models.Header` object that can have\nextended information about the header, such as a description, deprecation\nmarker, examples etc.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003ePossible types\u003c/th\u003e\n\u003cth\u003eExamples\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, str]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\"X-Requested-With\": \"Information about the creation of the request\"}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, Header]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\n    \"X-Requested-With\": Header(\n        description=\"Information about the creation of the request\",\n        required=True,\n        value_type=str,\n        deprecated=False,\n        allowEmptyValue=False,\n        example=\"XMLHttpRequest\",\n    )\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### cookies\n\nDictionary of request cookies applicable for the operation, where the key is\nthe cookie name and the value can be either a string or a `Cookie` object.\n\nIn the first case it is the cookie description. This affects the value of\nthe [`parameters`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`description`](https://spec.openapis.org/oas/v3.1.0#parameter-object)\nfield of Parameter object.\n\nIn the second case it is `openapify.core.models.Cookie` object that can have\nextended information about the cookie, such as a description, deprecation\nmarker, examples etc.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003ePossible types\u003c/th\u003e\n\u003cth\u003eExamples\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, str]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\"__ga\": \"A randomly generated number as a client ID\"}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, Cookie]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\n    \"__ga\": Cookie(\n        description=\"A randomly generated number as a client ID\",\n        required=True,\n        value_type=str,\n        deprecated=False,\n        allowEmptyValue=False,\n        example=\"1.2.345678901.2345678901\",\n    )\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### Response\n\nDecorator `response_schema` describes a single response from the API Operation.\nResponse can have an HTTP code, body and headers. If the Operation supports\nmore than one response, then the decorator must be applied multiple times to\ncover each of them.\n\n```python\nfrom openapify import response_schema\n```\n\n#### body\n\nA Python data type for the response body for which\nthe JSON Schema will be built. This affects the value of\nthe [`responses`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`schema`](https://spec.openapis.org/oas/v3.1.0#media-type-object) field of\nMedia Type object inside the value\nof [`content`](https://spec.openapis.org/oas/v3.1.0#response-object) field\nof Response object.\n\n| Possible types | Examples |\n|----------------|----------|\n| `Type`         | `Book`   |\n\n#### http_code\n\nAn HTTP code of the response. This affects the value of\nthe [`responses`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely, the patterned key in\nthe [Responses](https://spec.openapis.org/oas/v3.1.0#responses-object) object.\n\n| Possible types | Examples |\n|----------------|----------|\n| `str`          | `\"200\"`  |\n| `int`          | `400`    |\n\n#### media_type\n\nA media type\nor [media type range](https://www.rfc-editor.org/rfc/rfc7231#appendix-D) of the\nresponse body. This affects the value of\nthe [`responses`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely, the key\nof [`content`](https://spec.openapis.org/oas/v3.1.0#response-object) field of\nResponse object.\n\nThe default value is `\"application/json\"`.\n\n| Possible types | Examples            |\n|----------------|---------------------|\n| `str`          | `\"application/xml\"` |\n\n####\n\n#### description\n\nA description of the response. [CommonMark syntax](https://spec.commonmark.org)\nMAY be used for rich text representation. This affects the value of\nthe [`responses`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`description`](https://spec.openapis.org/oas/v3.1.0#response-object) field\nof Response object.\n\n\n| Possible types | Examples                |\n|----------------|-------------------------|\n| `str`          | `\"Invalid ID Supplied\"` |\n\n#### headers\n\nDictionary of response headers applicable for the operation, where the key is\nthe header name and the value can be either a string or a `Header` object.\n\nIn the first case it is the header description. This affects the value of\nthe [`responses`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`description`](https://spec.openapis.org/oas/v3.1.0#header-object)\nfield of Header object.\n\nIn the second case it is `openapify.core.models.Header` object that can have\nextended information about the header, such as a description, deprecation\nmarker, examples etc.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003ePossible types\u003c/th\u003e\n\u003cth\u003eExamples\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, str]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\"Content-Location\": \"An alternate location for the returned data\"}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, Header]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\n    \"Content-Location\": Header(\n        description=\"An alternate location for the returned data\",\n        example=\"/index.htm\",\n    )\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### example\n\nExample of the response body. The example object SHOULD be in the correct format\nas specified by the media type. This affects the value of\nthe [`responses`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`example`](https://spec.openapis.org/oas/v3.1.0#media-type-object) field\nof Media Type object inside the value\nof [`content`](https://spec.openapis.org/oas/v3.1.0#response-object) field of\nResponse object.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003ePossible types\u003c/th\u003e\n\u003cth\u003eExamples\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eAny\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\n    \"title\": \"Anna Karenina\",\n    \"author\": \"Leo Tolstoy\",\n    \"year\": 1877,\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### examples\n\nExamples of the response body. Each example object SHOULD match the media type\nand specified schema if present. This affects the value of\nthe [`responses`](https://spec.openapis.org/oas/v3.1.0#operation-object)\nfield of the Operation object, or more precisely,\nthe [`examples`](https://spec.openapis.org/oas/v3.1.0#media-type-object) field\nof Media Type object inside the value\nof [`content`](https://spec.openapis.org/oas/v3.1.0#response-object) field of\nResponse object.\n\nThe values of this dictionary could be either examples themselves,\nor `openapify.core.openapi.models.Example` objects. In the latter case,\nextended information about examples, such as a summary and description, can be\nadded to the [Example](https://spec.openapis.org/oas/v3.1.0#example-object)\nobject.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003ePossible types\u003c/th\u003e\n\u003cth\u003eExamples\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, Any]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\n    \"Anna Karenina\": {\n        \"title\": \"Anna Karenina\",\n        \"author\": \"Leo Tolstoy\",\n        \"year\": 1877,\n    }\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e \u003ccode\u003eMapping[str, Example]\u003c/code\u003e \u003c/td\u003e\n\u003ctd\u003e\n\n```python\n{\n    \"Anna Karenina\": Example(\n        value={\n            \"title\": \"Anna Karenina\",\n            \"author\": \"Leo Tolstoy\",\n            \"year\": 1877,\n        },\n        summary=\"The book 'Anna Karenina'\",\n    )\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### Security requirements\n\nDecorator `security_requirements`\ndeclares [security mechanisms](https://spec.openapis.org/oas/v3.1.0#securityRequirementObject)\nthat can be used for the operation.\n\n```python\nfrom openapify import security_requirements\n```\n\nThis decorator takes one or more `SecurityRequirement` mappings, where the key\nis the requirement name and the value is `SecurityScheme` object. There are\nclasses for\neach [security scheme](https://spec.openapis.org/oas/v3.1.0#security-scheme-object)\nwhich can be imported as follows:\n\n```python\nfrom openapify.core.openapi.models import (\n    APIKeySecurityScheme,\n    HTTPSecurityScheme,\n    OAuth2SecurityScheme,\n    OpenIDConnectSecurityScheme,\n)\n```\n\nFor example, to add authorization by token, you can write something like this:\n\n```python\nfrom openapify import security_requirements\nfrom openapify.core.openapi.models import (\n    APIKeySecurityScheme,\n    SecuritySchemeAPIKeyLocation,\n)\n\nXAuthTokenSecurityRequirement = {\n    \"x-auth-token\": APIKeySecurityScheme(\n        name=\"X-Auh-Token\",\n        location=SecuritySchemeAPIKeyLocation.HEADER,\n    )\n}\n\n@security_requirements(XAuthTokenSecurityRequirement)\ndef secure_operation():\n    ...\n```\n\nAnd the generated specification document will look like this:\n\n```yaml\nopenapi: 3.1.0\ninfo:\n  title: API\n  version: 1.0.0\npaths:\n  /secure_path:\n    get:\n      security:\n      - x-auth-token: []\ncomponents:\n  securitySchemes:\n    x-auth-token:\n      type: apiKey\n      name: X-Auh-Token\n      in: header\n```\n\nPlugins\n--------------------------------------------------------------------------------\n\nSome aspects of creating an OpenAPI document can be changed using plugins.\nThere is `openapify.plugins.BasePlugin` base class, which has all the methods\navailable for definition. If you want to write a plugin that, for example, will\nonly generate schema for request parameters, then it will be enough for you to\ndefine only one appropriate method, and leave the rest non-implemented.\nPlugin system works by going through all registered plugins and calling\nthe appropriate method. If such a method raises `NotImplementedError` or\nreturns `None`, it is assumed that this plugin doesn't provide the necessary\nfunctionality. Iteration stops at the first plugin that returned something\nother than `None`.\n\nPlugins are registered via the `plugins` argument of the `build_spec` function:\n\n```python\nfrom openapify import BasePlugin, build_spec\n\n\nclass MyPlugin1(BasePlugin):\n    def schema_helper(...):\n        # return something meaningful here, see the following chapters\n        ...\n\n\nbuild_spec(..., plugins=[MyPlugin1()])\n```\n\n### `schema_helper`\n\nOpenAPI [Schema](https://spec.openapis.org/oas/v3.1.0#schemaObject) object\nis built from python types stored in the `value_type` attribute of the\nfollowing openapify dataclasses defined in `openapify.core.models`:\n* `Body`\n* `Cookie`\n* `Header`\n* `QueryParam`\n\nOut of the box, the schema is generated by using\n[`mashumaro`](https://github.com/Fatal1ty/mashumaro) library (see the note\nbelow), but support for third-party entity schema generators can be achieved\nthrough `schema_helper` method. For example, here's what a plugin for pydantic\nmodels might look like:\n\n```python\nfrom typing import Any\n\nfrom openapify import BasePlugin\nfrom openapify.core.models import Body, Cookie, Header, QueryParam\nfrom pydantic import BaseModel\n\n\nclass PydanticSchemaPlugin(BasePlugin):\n    def schema_helper(\n        self,\n        obj: Body | Cookie | Header | QueryParam,\n        name: str | None = None,\n    ) -\u003e dict[str, Any] | None:\n        if issubclass(obj.value_type, BaseModel):\n            schema = obj.value_type.model_json_schema(\n                ref_template=\"#/components/schemas/{model}\"\n            )\n            self.spec.components.schemas.update(schema.pop(\"$defs\", {}))\n            return schema\n```\n\n\u003e [!NOTE]\\\n\u003e The [`BaseSchemaPlugin`](https://github.com/Fatal1ty/openapify/blob/master/openapify/core/base_plugins.py#L41-L64),\n\u003e which is enabled by default and has the lowest priority, is responsible for\n\u003e generating the schema. This plugin utilizes the mashumaro library for schema\n\u003e generation, which in turn incorporates its own [plugin system](https://github.com/Fatal1ty/mashumaro?tab=readme-ov-file#json-schema-plugins),\n\u003e enabling customization of JSON Schema generation and support for additional\n\u003e data types. For more nuanced modifications, particularly within nested data\n\u003e models, you can employ `BaseSchemaPlugin` with a specified list of mashumaro JSON\n\u003e Schema plugins. This approach allows for finer control over schema generation\n\u003e when needed:\n\u003e ```python\n\u003e from mashumaro.jsonschema.plugins import DocstringDescriptionPlugin\n\u003e\n\u003e from openapify import build_spec\n\u003e from openapify.core.base_plugins import BaseSchemaPlugin\n\u003e\n\u003e spec = build_spec(\n\u003e     routes=[...],\n\u003e     plugins=[\n\u003e         BaseSchemaPlugin(\n\u003e             plugins=[\n\u003e                 DocstringDescriptionPlugin(),\n\u003e             ]\n\u003e         ),\n\u003e     ],\n\u003e )\n\u003e ```\n\n### media_type_helper\n\nA media type is used in OpenAPI Request\n[Body](https://spec.openapis.org/oas/v3.1.0#request-body-object) and\n[Response](https://spec.openapis.org/oas/v3.1.0#response-object) objects.\nBy default, `application/octet-stream` is applied for `bytes` or `bytearray`\ntypes, and `application/json` is applied otherwise. You can support more media\ntypes or override existing ones with `media_type_helper` method.\n\nLet's imagine that you have an API route that returns PNG images as the body.\nYou can have a separate model class representing images, but the more common\ncase is to use `typing.Annotated` wrapper for bytes. Here's what a plugin for\n`image/png` media type might look like:\n\n```python\nfrom typing import Annotated, Any, Dict, Optional\n\nfrom openapify import BasePlugin, build_spec, response_schema\nfrom openapify.core.models import Body, RouteDef\n\nImagePNG = Annotated[bytes, \"PNG\"]\n\n\nclass ImagePNGPlugin(BasePlugin):\n    def media_type_helper(\n        self, body: Body, schema: Dict[str, Any]\n    ) -\u003e Optional[str]:\n        if body.value_type is ImagePNG:\n            return \"image/png\"\n\n\n@response_schema(body=ImagePNG)\ndef foo():\n    ...\n\n\nroutes = [RouteDef(\"/foo\", \"get\", foo)]\nspec = build_spec(routes, plugins=[ImagePNGPlugin()])\nprint(spec.to_yaml())\n```\n\nThe resulting document will contain `image/png` content in the response:\n```yaml\nopenapi: 3.1.0\ninfo:\n  title: API\n  version: 1.0.0\npaths:\n  /foo:\n    get:\n      responses:\n        '200':\n          description: OK\n          content:\n            image/png:\n              schema: {}\n```\n","funding_links":["https://coindrop.to/tikhonov_a"],"categories":["Python","api"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFatal1ty%2Fopenapify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFatal1ty%2Fopenapify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFatal1ty%2Fopenapify/lists"}