# Open API Pages
[](https://pypi.org/project/openapipages)
[](https://pypi.org/project/openapipages)
[](https://github.com/hasansezertasan/openapipages/blob/main/LICENSE)
[](https://github.com/hasansezertasan/openapipages)
[](https://pepy.tech/project/openapipages)
[](https://pepy.tech/project/openapipages)
[](https://pepy.tech/project/openapipages)
Totally Pythonic, OpenAPI Based customizable documentation pages for [SwaggerUI], [ReDoc], [RapiDoc], [Elements], [Scalar].
> Keep in mind, that this package doesn't generate [OpenAPI] Spec, it just renders the pages with the given configuration.
---
## Table of Contents
- [Open API Pages](#open-api-pages)
- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Progress](#progress)
- [Installation](#installation)
- [Usage](#usage)
- [FastAPI](#fastapi)
- [Litestar](#litestar)
- [Motivation](#motivation)
- [Developer Experience](#developer-experience)
- [Configuration](#configuration)
- [Alternatives](#alternatives)
- [Standardisation](#standardisation)
- [See Also](#see-also)
- [Projects](#projects)
- [Issues, PRs, and Discussions](#issues-prs-and-discussions)
- [Author](#author)
- [Disclaimer](#disclaimer)
- [License](#license)
## Features
> Gimme an OpenAPI Spec, leave the rest to me...
- Framework agnostic.
- Zero dependencies, just Python standard library.
- Fully typed.
- Highly extensible.
### Progress
| Documentation | Page | Config |
| ------------- | ------------------ | ------------------ |
| [SwaggerUI] | :white_check_mark: | :heavy_check_mark: |
| [ReDoc] | :white_check_mark: | :heavy_check_mark: |
| [RapiDoc] | :white_check_mark: | :heavy_check_mark: |
| [Elements] | :white_check_mark: | :heavy_check_mark: |
| [Scalar] | :white_check_mark: | :heavy_check_mark: |
Emoji Key:
| Emoji | Meaning |
| --------------------- | ----------- |
| :white_check_mark: | Ready |
| :heavy_check_mark: | Partially |
| :x: | Failed |
| :construction: | In Progress |
| :white_square_button: | Pending |
| :warning: | Not sure |
## Installation
```console
pip install openapipages
```
## Usage
I know it looks a bit boilerplate but it's all straight-forward. The `.render()` method returns the HTML as a string. Thanks to this design, you can extend and configure the pages as you wish (e.g. add extra logic to restrict access to the page).
### FastAPI
> The `include_in_schema` parameter is set to `False` in each endpoint to avoid including these endpoints in the OpenAPI Spec.
```python
from fastapi import FastAPI
from fastapi.responses import HTMLResponse
from openapipages import Elements, RapiDoc, ReDoc, Scalar, SwaggerUI
# Disable the built-in /redoc page so we can make a custom one.
app = FastAPI(redoc_url=None)
@app.get("/")
def root() -> dict[str, str]:
return {"Hello": "World"}
@app.get("/swaggerui", response_class=HTMLResponse, include_in_schema=False)
def get_swaggerui() -> str:
return SwaggerUI(title="Swagger UI").render()
@app.get("/redoc", response_class=HTMLResponse, include_in_schema=False)
def get_redoc() -> str:
return ReDoc(title="ReDoc").render()
@app.get("/scalar", response_class=HTMLResponse, include_in_schema=False)
def get_scalar() -> str:
return Scalar(title="Scalar").render()
@app.get("/elements", response_class=HTMLResponse, include_in_schema=False)
def get_elements() -> str:
return Elements(title="Elements").render()
@app.get("/rapidoc", response_class=HTMLResponse, include_in_schema=False)
def get_rapidoc() -> str:
return RapiDoc(title="RapiDoc").render()
```
### Litestar
> The `include_in_schema` parameter is set to `False` in each endpoint to avoid including these endpoints in the OpenAPI Spec.
```python
from litestar import Litestar, MediaType, get
from openapipages import Elements, RapiDoc, ReDoc, Scalar, SwaggerUI
openapi_url = "/schema/openapi.json"
@get("/")
def root() -> dict[str, str]:
return {"Hello": "World"}
@get("/swaggerui", media_type=MediaType.HTML, include_in_schema=False)
def get_swaggerui() -> str:
return SwaggerUI(title="Swagger UI", openapi_url=openapi_url).render()
@get("/redoc", media_type=MediaType.HTML, include_in_schema=False)
def get_redoc() -> str:
return ReDoc(title="ReDoc", openapi_url=openapi_url).render()
@get("/scalar", media_type=MediaType.HTML, include_in_schema=False)
def get_scalar() -> str:
return Scalar(title="Scalar", openapi_url=openapi_url).render()
@get("/elements", media_type=MediaType.HTML, include_in_schema=False)
def get_elements() -> str:
return Elements(title="Elements", openapi_url=openapi_url).render()
@get("/rapidoc", media_type=MediaType.HTML, include_in_schema=False)
def get_rapidoc() -> str:
return RapiDoc(title="RapiDoc", openapi_url=openapi_url).render()
app = Litestar([root, get_swaggerui, get_redoc, get_scalar, get_elements, get_rapidoc])
```
## Motivation
TL;DR - I don't want to copy and paste it again...
### Developer Experience
Several API Documentation tools are ready to use at your fingertips with a standard interface.
No more copying and pasting the same thing from one project to another. Import the package and use it!
### Configuration
Here is a pull request made to the [FastAPI] repo. This was the point I understood the configuration was limited and it wouldn't change...
- [Allow passing ui parameters to redoc html by adriantre · Pull Request #10437 · tangelo/fastapi](https://github.com/tiangolo/fastapi/pull/10437)
Also, the author's answer to this PR shows that we won't be seeing more alternative documentation tools in the future.
### Alternatives
Here is another pull request made to the [FastAPI] repo. It brings [Scalar] support, but it's not approved/merged yet and I think it will stay that way thanks to the previous PR.
- [feat: add scalar integration (additional alternative to Swagger UI/Redoc) by marclave · Pull Request #10674 · tiangolo/fastapi](https://github.com/tiangolo/fastapi/pull/10674)
### Standardisation
> A standard interface for many API Documentation Interfaces with configuration features.
Lately, OpenAPI Spec-based Documentation tools have become popular in the Python community. We see a lot of projects ([FastAPI], [Litestar], [APISpec], [flasgger], [SpecTree], [Connexion], etc) offering support for OpenAPI Specification out of the box.
[Litestar] has support for [SwaggerUI], [ReDoc], [RapiDoc], and [Elements] and [FastAPI] has support for [SwaggerUI], and [ReDoc] but what is next? Will the next one be enough?
They all have one thing in common, some HTML (as Python string or a file) templated with the given configuration.
Do you see where I am going?
I want `openapipages` to be SQLAlchemy of OpenAPI Spec-based Documentation tools.
One interface for many! And of course Framework agnostic... So you can use it in your [FastAPI], [Litestar] projects, or any other project that generates OpenAPI specifications.
## See Also
### Projects
- [kemingy/defspec: Create the OpenAPI spec and document from dataclass, attrs, etc.](https://github.com/kemingy/defspec/)
- [spec-first/swagger_ui_bundle: bundled swagger-ui pip package](https://github.com/spec-first/swagger_ui_bundle)
- [spec-first/connexion: Connexion is a modern Python web framework that makes spec-first and api-first development easy.][Connexion]
- [sveint/flask-swagger-ui: Swagger UI blueprint for flask](https://github.com/sveint/flask-swagger-ui)
- [flasgger/flasgger: Easy OpenAPI specs and Swagger UI for your Flask API][flasgger]
- [marshmallow-code/apispec: A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification)..][APISpec]
- [jmcarp/flask-apispec][Flask-apispec]
### Issues, PRs, and Discussions
- [[Question] Is it possible to load the Swagger UI offline? · Issue #261 · 0b01001001/spectree](https://github.com/0b01001001/spectree/issues/261)
- [Swagger with hosted files does not work after upgrade · tiangolo/fastapi · Discussion #10426](https://github.com/tiangolo/fastapi/discussions/10426)
- [♻️ Generate cleaner Swagger HTML by s-rigaud · Pull Request #11072 · tiangolo/fastapi](https://github.com/tiangolo/fastapi/pull/11072)
## Author
- [Hasan Sezer Tasan](https://www.github.com/hasansezertasan), It's me :wave:
## Disclaimer
[FastAPI] and [Litestar] projects and the two pull requests mentioned above inspired me to create this package.
## License
`openapipages` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
<!-- Links -->
[OpenAPI]: https://github.com/OAI/OpenAPI-Specification
<!-- Python Projects -->
[FastAPI]: https://github.com/tiangolo/fastapi
[Litestar]: https://github.com/litestar-org/litestar
[SpecTree]: https://github.com/0b01001001/spectree
[flasgger]: https://github.com/flasgger/flasgger
[Connexion]: https://github.com/spec-first/connexion
[APISpec]: https://github.com/marshmallow-code/apispec
[Flask-apispec]: https://github.com/jmcarp/flask-apispec
<!-- API Documentation Tools -->
[Scalar]: https://github.com/scalar/scalar
[Elements]: https://github.com/stoplightio/elements
[RapiDoc]: https://github.com/rapi-doc/RapiDoc
[ReDoc]: https://github.com/Redocly/redoc
[SwaggerUI]: https://github.com/swagger-api/swagger-ui
Raw data
{
"_id": null,
"home_page": null,
"name": "openapipages",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Hasan Sezer Ta\u015fan <hasansezertasan@gmail.com>",
"keywords": "api, documentation, elements, fastapi, flask, litestar, openapi, openapipages, rapidoc, redoc, scalar, spec, specification, swagger, swagger-ui",
"author": null,
"author_email": "Hasan Sezer Ta\u015fan <hasansezertasan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0b/0b/65cd790394c3b9294bdbf0b4e8fcf8a51171c177dc908d1f7d586a3d6f5e/openapipages-0.1.2.tar.gz",
"platform": null,
"description": "# Open API Pages\n\n[](https://pypi.org/project/openapipages)\n[](https://pypi.org/project/openapipages)\n[](https://github.com/hasansezertasan/openapipages/blob/main/LICENSE)\n[](https://github.com/hasansezertasan/openapipages)\n\n[](https://pepy.tech/project/openapipages)\n[](https://pepy.tech/project/openapipages)\n[](https://pepy.tech/project/openapipages)\n\nTotally Pythonic, OpenAPI Based customizable documentation pages for [SwaggerUI], [ReDoc], [RapiDoc], [Elements], [Scalar].\n\n> Keep in mind, that this package doesn't generate [OpenAPI] Spec, it just renders the pages with the given configuration.\n\n---\n\n## Table of Contents\n\n- [Open API Pages](#open-api-pages)\n - [Table of Contents](#table-of-contents)\n - [Features](#features)\n - [Progress](#progress)\n - [Installation](#installation)\n - [Usage](#usage)\n - [FastAPI](#fastapi)\n - [Litestar](#litestar)\n - [Motivation](#motivation)\n - [Developer Experience](#developer-experience)\n - [Configuration](#configuration)\n - [Alternatives](#alternatives)\n - [Standardisation](#standardisation)\n - [See Also](#see-also)\n - [Projects](#projects)\n - [Issues, PRs, and Discussions](#issues-prs-and-discussions)\n - [Author](#author)\n - [Disclaimer](#disclaimer)\n - [License](#license)\n\n## Features\n\n> Gimme an OpenAPI Spec, leave the rest to me...\n\n- Framework agnostic.\n- Zero dependencies, just Python standard library.\n- Fully typed.\n- Highly extensible.\n\n### Progress\n\n| Documentation | Page | Config |\n| ------------- | ------------------ | ------------------ |\n| [SwaggerUI] | :white_check_mark: | :heavy_check_mark: |\n| [ReDoc] | :white_check_mark: | :heavy_check_mark: |\n| [RapiDoc] | :white_check_mark: | :heavy_check_mark: |\n| [Elements] | :white_check_mark: | :heavy_check_mark: |\n| [Scalar] | :white_check_mark: | :heavy_check_mark: |\n\nEmoji Key:\n\n| Emoji | Meaning |\n| --------------------- | ----------- |\n| :white_check_mark: | Ready |\n| :heavy_check_mark: | Partially |\n| :x: | Failed |\n| :construction: | In Progress |\n| :white_square_button: | Pending |\n| :warning: | Not sure |\n\n## Installation\n\n```console\npip install openapipages\n```\n\n## Usage\n\nI know it looks a bit boilerplate but it's all straight-forward. The `.render()` method returns the HTML as a string. Thanks to this design, you can extend and configure the pages as you wish (e.g. add extra logic to restrict access to the page).\n\n### FastAPI\n\n> The `include_in_schema` parameter is set to `False` in each endpoint to avoid including these endpoints in the OpenAPI Spec.\n\n```python\nfrom fastapi import FastAPI\nfrom fastapi.responses import HTMLResponse\nfrom openapipages import Elements, RapiDoc, ReDoc, Scalar, SwaggerUI\n\n# Disable the built-in /redoc page so we can make a custom one.\napp = FastAPI(redoc_url=None)\n\n\n@app.get(\"/\")\ndef root() -> dict[str, str]:\n return {\"Hello\": \"World\"}\n\n\n@app.get(\"/swaggerui\", response_class=HTMLResponse, include_in_schema=False)\ndef get_swaggerui() -> str:\n return SwaggerUI(title=\"Swagger UI\").render()\n\n\n@app.get(\"/redoc\", response_class=HTMLResponse, include_in_schema=False)\ndef get_redoc() -> str:\n return ReDoc(title=\"ReDoc\").render()\n\n\n@app.get(\"/scalar\", response_class=HTMLResponse, include_in_schema=False)\ndef get_scalar() -> str:\n return Scalar(title=\"Scalar\").render()\n\n\n@app.get(\"/elements\", response_class=HTMLResponse, include_in_schema=False)\ndef get_elements() -> str:\n return Elements(title=\"Elements\").render()\n\n\n@app.get(\"/rapidoc\", response_class=HTMLResponse, include_in_schema=False)\ndef get_rapidoc() -> str:\n return RapiDoc(title=\"RapiDoc\").render()\n\n```\n\n### Litestar\n\n> The `include_in_schema` parameter is set to `False` in each endpoint to avoid including these endpoints in the OpenAPI Spec.\n\n```python\nfrom litestar import Litestar, MediaType, get\nfrom openapipages import Elements, RapiDoc, ReDoc, Scalar, SwaggerUI\n\nopenapi_url = \"/schema/openapi.json\"\n\n\n@get(\"/\")\ndef root() -> dict[str, str]:\n return {\"Hello\": \"World\"}\n\n\n@get(\"/swaggerui\", media_type=MediaType.HTML, include_in_schema=False)\ndef get_swaggerui() -> str:\n return SwaggerUI(title=\"Swagger UI\", openapi_url=openapi_url).render()\n\n\n@get(\"/redoc\", media_type=MediaType.HTML, include_in_schema=False)\ndef get_redoc() -> str:\n return ReDoc(title=\"ReDoc\", openapi_url=openapi_url).render()\n\n\n@get(\"/scalar\", media_type=MediaType.HTML, include_in_schema=False)\ndef get_scalar() -> str:\n return Scalar(title=\"Scalar\", openapi_url=openapi_url).render()\n\n\n@get(\"/elements\", media_type=MediaType.HTML, include_in_schema=False)\ndef get_elements() -> str:\n return Elements(title=\"Elements\", openapi_url=openapi_url).render()\n\n\n@get(\"/rapidoc\", media_type=MediaType.HTML, include_in_schema=False)\ndef get_rapidoc() -> str:\n return RapiDoc(title=\"RapiDoc\", openapi_url=openapi_url).render()\n\n\napp = Litestar([root, get_swaggerui, get_redoc, get_scalar, get_elements, get_rapidoc])\n\n```\n\n## Motivation\n\nTL;DR - I don't want to copy and paste it again...\n\n### Developer Experience\n\nSeveral API Documentation tools are ready to use at your fingertips with a standard interface.\n\nNo more copying and pasting the same thing from one project to another. Import the package and use it!\n\n### Configuration\n\nHere is a pull request made to the [FastAPI] repo. This was the point I understood the configuration was limited and it wouldn't change...\n\n- [Allow passing ui parameters to redoc html by adriantre \u00b7 Pull Request #10437 \u00b7 tangelo/fastapi](https://github.com/tiangolo/fastapi/pull/10437)\n\nAlso, the author's answer to this PR shows that we won't be seeing more alternative documentation tools in the future.\n\n### Alternatives\n\nHere is another pull request made to the [FastAPI] repo. It brings [Scalar] support, but it's not approved/merged yet and I think it will stay that way thanks to the previous PR.\n\n- [feat: add scalar integration (additional alternative to Swagger UI/Redoc) by marclave \u00b7 Pull Request #10674 \u00b7 tiangolo/fastapi](https://github.com/tiangolo/fastapi/pull/10674)\n\n### Standardisation\n\n> A standard interface for many API Documentation Interfaces with configuration features.\n\nLately, OpenAPI Spec-based Documentation tools have become popular in the Python community. We see a lot of projects ([FastAPI], [Litestar], [APISpec], [flasgger], [SpecTree], [Connexion], etc) offering support for OpenAPI Specification out of the box.\n\n[Litestar] has support for [SwaggerUI], [ReDoc], [RapiDoc], and [Elements] and [FastAPI] has support for [SwaggerUI], and [ReDoc] but what is next? Will the next one be enough?\n\nThey all have one thing in common, some HTML (as Python string or a file) templated with the given configuration.\n\nDo you see where I am going?\n\nI want `openapipages` to be SQLAlchemy of OpenAPI Spec-based Documentation tools.\n\nOne interface for many! And of course Framework agnostic... So you can use it in your [FastAPI], [Litestar] projects, or any other project that generates OpenAPI specifications.\n\n## See Also\n\n### Projects\n\n- [kemingy/defspec: Create the OpenAPI spec and document from dataclass, attrs, etc.](https://github.com/kemingy/defspec/)\n- [spec-first/swagger_ui_bundle: bundled swagger-ui pip package](https://github.com/spec-first/swagger_ui_bundle)\n- [spec-first/connexion: Connexion is a modern Python web framework that makes spec-first and api-first development easy.][Connexion]\n- [sveint/flask-swagger-ui: Swagger UI blueprint for flask](https://github.com/sveint/flask-swagger-ui)\n- [flasgger/flasgger: Easy OpenAPI specs and Swagger UI for your Flask API][flasgger]\n- [marshmallow-code/apispec: A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification)..][APISpec]\n- [jmcarp/flask-apispec][Flask-apispec]\n\n### Issues, PRs, and Discussions\n\n- [[Question] Is it possible to load the Swagger UI offline? \u00b7 Issue #261 \u00b7 0b01001001/spectree](https://github.com/0b01001001/spectree/issues/261)\n- [Swagger with hosted files does not work after upgrade \u00b7 tiangolo/fastapi \u00b7 Discussion #10426](https://github.com/tiangolo/fastapi/discussions/10426)\n- [\u267b\ufe0f Generate cleaner Swagger HTML by s-rigaud \u00b7 Pull Request #11072 \u00b7 tiangolo/fastapi](https://github.com/tiangolo/fastapi/pull/11072)\n\n## Author\n\n- [Hasan Sezer Tasan](https://www.github.com/hasansezertasan), It's me :wave:\n\n## Disclaimer\n\n[FastAPI] and [Litestar] projects and the two pull requests mentioned above inspired me to create this package.\n\n## License\n\n`openapipages` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n\n<!-- Links -->\n[OpenAPI]: https://github.com/OAI/OpenAPI-Specification\n<!-- Python Projects -->\n[FastAPI]: https://github.com/tiangolo/fastapi\n[Litestar]: https://github.com/litestar-org/litestar\n[SpecTree]: https://github.com/0b01001001/spectree\n[flasgger]: https://github.com/flasgger/flasgger\n[Connexion]: https://github.com/spec-first/connexion\n[APISpec]: https://github.com/marshmallow-code/apispec\n[Flask-apispec]: https://github.com/jmcarp/flask-apispec\n<!-- API Documentation Tools -->\n[Scalar]: https://github.com/scalar/scalar\n[Elements]: https://github.com/stoplightio/elements\n[RapiDoc]: https://github.com/rapi-doc/RapiDoc\n[ReDoc]: https://github.com/Redocly/redoc\n[SwaggerUI]: https://github.com/swagger-api/swagger-ui\n",
"bugtrack_url": null,
"license": null,
"summary": "OpenAPI Spec-based pages (SwaggerUI, ReDoc, RapiDoc, Elements, Scalar) ready with configuration features.",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/hasansezertasan/openapipages#readme",
"Issues": "https://github.com/hasansezertasan/openapipages/issues",
"Source": "https://github.com/hasansezertasan/openapipages"
},
"split_keywords": [
"api",
" documentation",
" elements",
" fastapi",
" flask",
" litestar",
" openapi",
" openapipages",
" rapidoc",
" redoc",
" scalar",
" spec",
" specification",
" swagger",
" swagger-ui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4c4b243292f8cfad1b0160d48f5988d5673ae34e6ee0f444027010099bc2d94c",
"md5": "a13c1098d9457c5b6293f2cefeaef18e",
"sha256": "7495b69659c06ade718f3efa257a074c05813ec8cfe85b131935f6dcbd018c8b"
},
"downloads": -1,
"filename": "openapipages-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a13c1098d9457c5b6293f2cefeaef18e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12928,
"upload_time": "2024-07-22T23:42:58",
"upload_time_iso_8601": "2024-07-22T23:42:58.646150Z",
"url": "https://files.pythonhosted.org/packages/4c/4b/243292f8cfad1b0160d48f5988d5673ae34e6ee0f444027010099bc2d94c/openapipages-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0b0b65cd790394c3b9294bdbf0b4e8fcf8a51171c177dc908d1f7d586a3d6f5e",
"md5": "847ea8f5f7d9f8433f85008943283135",
"sha256": "9adc7ec19997f0b0f27e5123606feaf63f09f8ef9910085174591e68cf699e20"
},
"downloads": -1,
"filename": "openapipages-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "847ea8f5f7d9f8433f85008943283135",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15064,
"upload_time": "2024-07-22T23:43:00",
"upload_time_iso_8601": "2024-07-22T23:43:00.041151Z",
"url": "https://files.pythonhosted.org/packages/0b/0b/65cd790394c3b9294bdbf0b4e8fcf8a51171c177dc908d1f7d586a3d6f5e/openapipages-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-22 23:43:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hasansezertasan",
"github_project": "openapipages#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "openapipages"
}
JSON
