Skip to content

OpenAPI

Auto-generated OpenAPI 3.1 specification for your API.

Snaapi automatically generates an OpenAPI 3.1.0 specification that describes your entire API. It covers all enabled resources, their endpoints, request and response schemas, query parameters, and authentication requirements. This makes it easy to explore your API with standard tooling.

Auto-generated spec

Snaapi generates a single, unified OpenAPI specification covering all enabled resources. The spec includes:

  • All CRUD endpoints (GET, POST, PUT, PATCH, DELETE) for every resource
  • Server-Sent Events streaming endpoints
  • Request body schemas derived from field definitions
  • JSON:API response schemas with data, attributes, relationships, and links
  • Query parameter definitions with defaults (for example, _limit: 50, _offset: 0)
  • Filter operator documentation per field
  • Bearer token (JWT) security scheme

The spec is regenerated whenever a resource definition changes, so it always reflects the current state of your API.

Accessing the spec

The full OpenAPI spec is available at the root of your Snaapi instance.

Format Endpoint Content-Type
JSON /openapi.json application/json
YAML /openapi.yaml text/yaml

Example:

GET /openapi.json
GET /openapi.yaml

By default, the OpenAPI spec endpoints are public and no authentication is required to access them. To require an authenticated request, set the SNAAPI_OPENAPI_PRIVATE environment variable to true on your API. When private, callers must pass an Authorization: Bearer <key> header.

Using with Swagger UI

You can point Swagger UI (or any OpenAPI-compatible tool) at the spec endpoint to get an interactive API explorer.

Hosted Swagger UI

Use the public Swagger UI by passing your spec URL as a query parameter.

https://petstore.swagger.io/?url=https://your-api.snaapi.cloud/openapi.json

Other compatible tools

The generated specs work with any tool that supports OpenAPI 3.1.0, including:

  • Redoc. Clean, responsive API documentation.
  • Insomnia. Import the spec to generate request templates.
  • Postman. Import as an OpenAPI collection.
  • openapi-generator. Generate client SDKs in multiple languages.