Create the OpenAPI spec and document from dataclass, attrs, msgspec, etc.
Note
There are also lots of other projects can generate the OpenAPI document or even validate the data. This project is not intended to replace them.
This project is a legacy of a private initiative. During the development, I discovered that using msgspec could elegantly define and generate the API schema. The OpenAPI component can be utilized to generate the API documentation for various projects. As a result, I made the decision to extract it and transform it into a public project.
You can use this project as a low-level component or a drop-in module when you don't want to introduce too many other dependencies.
pip install defspec
# to enable the offline feature
pip install defspec[offline]flask: examples/flaskfalcon: examples/falconoffline: examples/offline
You can run the above examples and open the OpenAPI document in your browser:
swagger: http://127.0.0.1:8000/openapi/swaggerredoc: http://127.0.0.1:8000/openapi/redocscalar: http://127.0.0.1:8000/openapi/scalar
from dataclasses import dataclass
from typing import List
from defspec import OpenAPI, OpenAPIComponent, SecuritySchemeHTTP
@dataclass
class User:
name: str
age: int
openapi = OpenAPI(
components=OpenAPIComponent(
security_schemes={"token": SecuritySchemeHTTP(scheme="bearer")}
),
security=[{"token": []}],
)
openapi.register_route("/", method="get", summary="Hello World")
openapi.register_route(
"/users", method="post", summary="Get all the user info", response_type=List[User]
)
# get the OpenAPI spec
print(openapi.to_dict())
# get the OpenAPI spec bytes
with open("openapi.json", "wb") as f:
f.write(openapi.to_json())
# serve as a HTTP server
openapi.serve_as_http_daemon(port=8000, run_in_background=True)