{"id":14065354,"url":"https://github.com/Neoteroi/essentials-openapi","last_synced_at":"2025-07-29T20:32:18.666Z","repository":{"id":40445496,"uuid":"308764789","full_name":"Neoteroi/essentials-openapi","owner":"Neoteroi","description":"Functions to handle OpenAPI Documentation.","archived":false,"fork":false,"pushed_at":"2024-04-14T08:41:44.000Z","size":575,"stargazers_count":21,"open_issues_count":11,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-29T17:08:34.185Z","etag":null,"topics":["documentation","documentation-generator","openapi","swagger"],"latest_commit_sha":null,"homepage":"","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/Neoteroi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":{"github":"RobertoPrevato"}},"created_at":"2020-10-30T23:25:32.000Z","updated_at":"2024-04-01T07:00:41.000Z","dependencies_parsed_at":"2024-04-14T07:40:56.708Z","dependency_job_id":"c6b32cec-c52a-478c-9d31-8ea9b4a18e19","html_url":"https://github.com/Neoteroi/essentials-openapi","commit_stats":{"total_commits":32,"total_committers":2,"mean_commits":16.0,"dds":0.03125,"last_synced_commit":"f879a927ebdf29570b2ffc16ecab218dd15b7a2b"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2Fessentials-openapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2Fessentials-openapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2Fessentials-openapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2Fessentials-openapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Neoteroi","download_url":"https://codeload.github.com/Neoteroi/essentials-openapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228046140,"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":["documentation","documentation-generator","openapi","swagger"],"created_at":"2024-08-13T07:04:26.784Z","updated_at":"2024-12-04T04:31:02.594Z","avatar_url":"https://github.com/Neoteroi.png","language":"Python","readme":"![Build](https://github.com/Neoteroi/essentials-openapi/workflows/Build/badge.svg)\r\n[![pypi](https://img.shields.io/pypi/v/essentials-openapi.svg)](https://pypi.python.org/pypi/essentials-openapi)\r\n[![versions](https://img.shields.io/pypi/pyversions/essentials-openapi.svg)](https://github.com/neoteroi/essentials-openapi)\r\n[![license](https://img.shields.io/github/license/neoteroi/essentials-openapi.svg)](https://github.com/neoteroi/essentials-openapi/blob/main/LICENSE)\r\n[![codecov](https://codecov.io/gh/Neoteroi/essentials-openapi/branch/main/graph/badge.svg?token=WEZ8YECJDF)](https://codecov.io/gh/Neoteroi/essentials-openapi)\r\n\r\n# essentials-openapi\r\n\r\nClasses to generate [OpenAPI Documentation](https://swagger.io/specification/)\r\nv3 and v2, in JSON and YAML, and to generate other kinds of documents from\r\nOpenAPI Documentation files.\r\n\r\n```bash\r\npip install essentials-openapi\r\n```\r\n\r\nTo install with dependencies to generate other kinds of artifacts from source\r\nOpenAPI Documentation files:\r\n\r\n```bash\r\npip install essentials-openapi[full]\r\n```\r\n\r\n## Useful links\r\n\r\n* https://swagger.io/specification/\r\n* https://editor.swagger.io\r\n\r\n## Usage\r\nThis library has been originally created to implement generation of OpenAPI Documentation\r\nin the [`BlackSheep` web framework](https://github.com/RobertoPrevato/BlackSheep).\r\nHowever, this package is abstracted from that web framework and can be reused for other\r\napplications. Today this library also offers functions to generate documentation from\r\nsource OpenAPI Documentation files.\r\n\r\n## Features to generate artifacts from Open API Documentation\r\n\r\nThese require the full package: install it using `pip install essentials-openapi[full]`.\r\n\r\nTo generate output for [MkDocs](https://www.mkdocs.org) and [PyMdown extentions](https://facelessuser.github.io/pymdown-extensions/):\r\n\r\n```bash\r\noad gen-docs -s example1-openapi.json -d output.md\r\n```\r\n\r\n![Example MkDocs documentation](https://gist.githubusercontent.com/RobertoPrevato/38a0598b515a2f7257c614938843b99b/raw/06e157c4f49e27a7e488d72d36d199194e28e952/oad-example-1.png)\r\n\r\n_Example of MkDocs documentation generated using [Neoteroi/mkdocs-plugins](https://github.com/Neoteroi/mkdocs-plugins)._\r\n\r\n---\r\n\r\nTo generate a [PlantUML](https://plantuml.com) [class\r\ndiagram](https://plantuml.com/class-diagram) of the components schemas:\r\n\r\n```bash\r\noad gen-docs -s source-openapi.json -d schemas.wsd --style \"PLANTUML_SCHEMAS\"\r\n```\r\n\r\n![Example schemas](https://gist.githubusercontent.com/RobertoPrevato/38a0598b515a2f7257c614938843b99b/raw/06e157c4f49e27a7e488d72d36d199194e28e952/oad-example-schemas.png)\r\n\r\n_Example of PlantUML diagram generated from components schemas._\r\n\r\n---\r\n\r\nTo generate a [PlantUML](https://plantuml.com) [class\r\ndiagram](https://plantuml.com/class-diagram) with an overview of API endpoints:\r\n\r\n```bash\r\noad gen-docs -s source-openapi.json -d schemas.wsd --style \"PLANTUML_API\"\r\n```\r\n\r\n![Example api overview](https://gist.githubusercontent.com/RobertoPrevato/38a0598b515a2f7257c614938843b99b/raw/3c6fdf85f6dd1a99ba1bd0486707dff557ff4ac4/oad-api-example.png)\r\n\r\n_Example of PlantUML diagram generated from path items._\r\n\r\n### Goals\r\n\r\n* Provide an API to generate OpenAPI Documentation files.\r\n* Providing functions to handle OpenAPI Documentation, like those to generate\r\n  other kinds of documentation from source OpenAPI Documentation files.\r\n* Support enough features to be useful for the most common API scenarios,\r\n  especially for OAD files that are generated automatically from web frameworks.\r\n\r\n### Non-Goals\r\n\r\n* To implement the whole OAD Specification.\r\n* For the features that generate artifacts: OpenAPI Documentation files are\r\n  **supposed to be coming from trusted sources**. Trying to handle source files\r\n  from untrusted sources and potentially causing HTML injection is out of the\r\n  scope of this library.\r\n\r\n## Limitations\r\n\r\n* Partial support for Parameter properties: `style`, `allow_reserved`, `explode` are not\r\n  handled.\r\n* Doesn't implement validation of values, currently it is only concerned in generating\r\n  code from a higher level API (it might be extended in the future with classes for\r\n  validation).\r\n* The features to generate artifacts from OpenAPI Documentation currently support only\r\n  Version 3 of the specification.\r\n\r\n### Styles\r\n\r\n| Style            | Int value | Description                                  |\r\n| ---------------- | --------- | -------------------------------------------- |\r\n| MKDOCS           | 1         | Markdown for MkDocs and PyMdown extensions.  |\r\n| MARKDOWN         | 2         | Basic Markdown.                              |\r\n| HTML             | 3         | Plain HTML _(planned, not yet implemented)_. |\r\n| PLANTUML_SCHEMAS | 100       | PlantUML schema for components schemas.      |\r\n| PLANTUML_API     | 101       | PlantUML schema for API endpoints.           |\r\n\r\n### Supported sources for OpenAPI Documentation\r\n\r\n| Source                         | Example                                              |\r\n| ------------------------------ | ---------------------------------------------------- |\r\n| YAML file                      | `./docs/swagger.yaml`                                |\r\n| JSON file                      | `./docs/swagger.json`                                |\r\n| URL returning YAML on HTTP GET | `https://example-domain.net/swagger/v1/swagger.yaml` |\r\n| URL returning JSON on HTTP GET | `https://example-domain.net/swagger/v1/swagger.json` |\r\n","funding_links":["https://github.com/sponsors/RobertoPrevato"],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeoteroi%2Fessentials-openapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNeoteroi%2Fessentials-openapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeoteroi%2Fessentials-openapi/lists"}