Swastik Codes Docs for Python

API documentation and a request collection for your Python web app, built from the OpenAPI document you already have. Install it, add one line, and you get two pages:

Both pages have a Run in Swastik Codes button that opens the API in Swastik Codes as a collection.

• No dependencies. Standard library only.
• Small. The whole UI is one script and one stylesheet, about 29 KB over the wire, precompressed (brotli and gzip) and cached for a year.
• Cheap to serve. The merged document is built once and cached until your spec or config changes. Spec responses carry an ETag, so repeat visits get 304.

FastAPI

pip install swastik-codes

from fastapi import FastAPI
from swastik_codes import mount

app = FastAPI(title="My API")

# ... your routes ...

mount(app, config="swastik-codes.json")   # /swc/docs and /swc/collection

mount() reads FastAPI's own cached app.openapi(). FastAPI's /docs and /redoc keep working. Turn them off with FastAPI(docs_url=None, redoc_url=None) if you only want these pages. To serve them at /docs instead, use mount(app, prefix="") together with docs_url=None.

Starlette works the same way. Pass spec= with your document, because Starlette has no app.openapi().

Flask

Flask has no OpenAPI generator of its own. Pass the document from the library you use (flask-smorest, apispec) or a dict:

from swastik_codes import init_flask

init_flask(app, spec=lambda: api.spec.to_dict(), config="swastik-codes.json")

Django

Use the document from drf-spectacular (or any generator). Cache it so it is built once:

# urls.py (root)
import functools
from drf_spectacular.generators import SchemaGenerator
from swastik_codes import django_urls

spec = functools.cache(lambda: SchemaGenerator().get_schema(request=None, public=True))
urlpatterns += django_urls(spec=spec, config="swastik-codes.json")

Any ASGI or WSGI app

from swastik_codes import SwastikCodesMiddleware, SwastikCodesWSGI

app = SwastikCodesMiddleware(app, spec=my_openapi_dict)        # ASGI: Litestar, Quart, ...
wsgi_app = SwastikCodesWSGI(wsgi_app, spec=my_openapi_dict)    # WSGI: Bottle, Pyramid, ...

spec is always a dict or a function that returns one. A function is called on each page load, so it should be cheap or cached. The merge is only redone when it returns a different object.

Editing the pages: swastik-codes.json

python -m swastik_codes init      # writes a starter swastik-codes.json

Every field is optional. Your OpenAPI document provides the rest. The file is re-read when it changes, so you can edit it and reload the page.

{
  "title": "Flight OTA API",
  "version": "2.0",
  "description": "Markdown introduction.\n\n## Getting started\n\n1. Get a token.\n2. Send it as a bearer token.",
  "servers": [
    { "url": "https://sandbox.example.com", "description": "Sandbox" },
    { "url": "https://api.example.com", "description": "Production" }
  ],
  "theme": { "accent": "#0d9488", "mode": "system" },
  "tags": { "Search": { "name": "Flight search", "description": "Find flights." } },
  "groups": [
    { "name": "Start here", "tags": ["Authentication"] },
    { "name": "Flights", "tags": ["Search", "Bookings"] }
  ],
  "operations": {
    "GET /v2/bookings/{booking_id}": { "summary": "Read a held booking", "description": "Markdown." },
    "deleteCache": { "hidden": true }
  },
  "hide": ["/internal/*", "DELETE /admin/*"],
  "pages": [{ "title": "Errors", "body": "Markdown, tables included." }],
  "links": [{ "label": "Support", "url": "https://example.com/support" }],
  "languages": ["curl", "javascript", "python", "go", "php"]
}

The Swastik Codes logo, the "Built with Swastik Codes" credit and the Run in Swastik Codes button are part of the pages. They have no setting. Keys such as logo or hideRunButton are ignored with a warning.

Notes

• Sending requests. The collection page sends requests from the browser. Requests to the same server always work. Requests to another server need that server to allow CORS for your docs origin, as for any page that calls an API from the browser.
• Credentials. Tokens you enter are kept in the tab's session storage. They are never sent anywhere except with your requests.
• Security headers. The pages are sent with a strict Content-Security-Policy: no inline scripts, and scripts and styles from this server only. Pass csp=False to turn it off.
• Run in Swastik Codes opens https://swastik.codes/app?import=<your openapi.json>. For an API on localhost it offers the file to download instead, because a website can't reach your computer.

Licence

Proprietary, free to use. See LICENSE.md. © Shwastik Tech Solutions Pvt Ltd.