openapipages 0.1.2
Open API Pages
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
Table of Contents
Features
Progress
Installation
Usage
FastAPI
Litestar
Motivation
Developer Experience
Configuration
Alternatives
Standardisation
See Also
Projects
Issues, PRs, and Discussions
Author
Disclaimer
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
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.
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.
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
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
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.
spec-first/swagger_ui_bundle: bundled swagger-ui pip package
spec-first/connexion: Connexion is a modern Python web framework that makes spec-first and api-first development easy.
sveint/flask-swagger-ui: Swagger UI blueprint for flask
flasgger/flasgger: Easy OpenAPI specs and Swagger UI for your Flask API
marshmallow-code/apispec: A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification)..
jmcarp/flask-apispec
Issues, PRs, and Discussions
[Question] Is it possible to load the Swagger UI offline? · Issue #261 · 0b01001001/spectree
Swagger with hosted files does not work after upgrade · tiangolo/fastapi · Discussion #10426
♻️ Generate cleaner Swagger HTML by s-rigaud · Pull Request #11072 · tiangolo/fastapi
Author
Hasan Sezer Tasan, 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 license.
For personal and professional use. You cannot resell or redistribute these repositories in their original state.
There are no reviews.