OpenAPI 3.0 Documentation updates for policy service
Link to Existing ADR(Architecture Decision Record) :
(osdu/platform/system/home#97 (closed))
OpenAPI 3.0 related changes
FastAPI leverages Python's docstring feature to automatically generate Swagger documentation for each API endpoint.
The docstring is written in a specific format, using Python's standard """ triple quotes, and can include rich text formatting using the Markdown syntax.It parses the docstring to extract information such as the endpoint's description, parameters, request and response models, and any other relevant information.
- Swagger UI: http://localhost:8080/api/policy/v1/swagger
- api-docs (JSON) : http://localhost:8080/api/policy/v1/api-docs
Example
- including detailed and informative docstrings in our code, we can ensure that our API is well-documented and easy to use, and FastAPI will use these docstrings to automatically generate Swagger documentation for our API.
@router.get("/health")
async def health():
"""
## Health check endpoint, which does not depend on OPA.
This API does not require any headers or authentication.
The /health endpoint responds with a 200 HTTP status code when the service pod can receive requests.
The endpoint indicates that the service pod is healthy and reachable.
It does not indicate that the service is ready to serve requests.
"""
return {'message': 'Healthy'}-
The first line of the docstring (Health check endpoint, which does not depend on OPA.) is used as the summary of the endpoint in the Swagger documentation.
-
The following lines of the docstring (This API does not require any headers or authentication.) are used as the description of the endpoint in the Swagger documentation.
-
The final lines of the docstring (The /health endpoint responds with a 200 HTTP status code when the service pod can receive requests.___) are not used directly in the Swagger documentation, but they provide additional context and information about the endpoint that may be useful to users of the API.