Skip to content

OpenAPI

@ghuri/rest generates an OpenAPI 3.1 document from your URL patterns. It walks every API view and viewset reachable from ROOT_URLCONF (or the patterns or router you pass), and describes paths, methods, parameters, request bodies and responses using your serializers’ JSON Schema.

src/urls.ts
import { path, include } from '@ghuri/core'
import { SchemaView, SwaggerUIView, ScalarView } from '@ghuri/rest'
import { router } from './api/urls'
export const urlpatterns = [
path('api/schema/', SchemaView.asView({ title: 'Blog API', version: '1.0.0' }), { name: 'schema' }),
path('api/docs/', SwaggerUIView.asView({ urlName: 'schema' }), { name: 'swagger-ui' }),
path('api/reference/', ScalarView.asView({ urlName: 'schema' }), { name: 'scalar' }),
path('api/', include(router.urls)),
]

Projects created with ghuri startproject already have these three routes. They come before the router’s include() so that a viewset registered as schema or docs can’t shadow them.

  • GET /api/schema/ returns the schema as JSON (also as application/vnd.oai.openapi+json). The document is generated once and cached per URL conf; pass cacheSchema: false to rebuild it on every request.
  • GET /api/docs/ serves Swagger UI, loaded from a CDN, pointed at the schema. It sends the csrftoken cookie as X-CSRFToken, so “Try it out” works with session authentication.
  • GET /api/reference/ serves Scalar the same way.

SchemaView options: title, version, description, info, servers, and patterns plus prefix to document only part of the site (patterns: router, prefix: 'api/'). The docs views find the schema by urlName (reversed in the current namespace), or take a literal schemaUrl.

Neither UI adds a build step or bundles assets into your Worker. If your content security policy forbids third-party scripts, pass cdn (for example SwaggerUIView.asView({ urlName: 'schema', cdn: '/static/swagger-ui' })) to point at assets you host yourself.

The docs views use the same permission system as any other view. To publish docs only to staff:

SchemaView.asView({ title: 'Blog API', permissionClasses: [IsAdminUser] })

For client generation, or to commit the schema and review how it changes, write it to a file with generateschema (DRF’s command). It comes from RestFrameworkConfig, which startproject adds to INSTALLED_APPS. Older projects can add it themselves:

src/settings.ts
import { RestFrameworkConfig } from '@ghuri/rest'
INSTALLED_APPS: [/* … */, RestFrameworkConfig],
Terminal window
npx ghuri generateschema # YAML to stdout
npx ghuri generateschema --file openapi.yaml
npx ghuri generateschema --file openapi.json # JSON, from the extension
npx ghuri generateschema --format openapi-json --url https://api.example.com

It documents ROOT_URLCONF. If that routes a SchemaView, the command takes the view’s title, version, description, servers, patterns and prefix, so the file is the same document that /api/schema/ serves. --title, --description, --api-version and --url override them. See the CLI reference for every option.

Feed the file to openapi-typescript, orval or any OpenAPI 3.1 generator for typed clients, or import it into Postman or Insomnia. To fail CI when the API changes without the committed file being updated:

Terminal window
npx ghuri generateschema --file openapi.yaml && git diff --exit-code openapi.yaml

generateSchema() returns the same document as a plain object, for a snapshot test that fails when the API changes shape, or for your own command:

import { generateSchema } from '@ghuri/rest'
import { urlpatterns } from '../src/urls'
const schema = generateSchema(urlpatterns, { title: 'Blog API', version: '1.0.0' })
expect(schema).toMatchSnapshot()
// or just one router, mounted under api/
generateSchema(router, { title: 'Blog API', prefix: 'api/' })

generateSchema() is synchronous. Pass servers to fill the servers list.

Source Becomes
URL route and converters (<int:pk>) paths, path parameters with types
Viewset actions and APIView methods operations, operationId (listPosts, createPost, partialUpdatePost, publishPost)
serializerClass / getSerializerClass() request and response components.schemas
readOnly / writeOnly fields separate PostRequest / PatchedPostRequest input schemas and a Post output schema
Model field helpText, choices, maxLength description, enum, maxLength
paginationClass wrapped list response (count, next, previous, results) and its query parameters
Filter backends query parameters (search, ordering, filtersetFields)
Permissions, throttles, lookups 400, 401, 403, 404 and 429 responses where they can happen
authenticationClasses with a static securityScheme securitySchemes and per-operation security
permissionClasses allowing anonymous access an empty {} entry in security (authentication optional)

The authentication classes in @ghuri/auth/rest all carry a securityScheme; see API authentication. .json format suffix routes are left out.

helpText on model fields is the cheapest documentation you will ever write. It shows up in the admin, in this schema and in the tool descriptions of agents.

Use the @extendSchema decorator on a handler or action to add or replace parts of an operation. Like @action, it works as a TC39 or legacy decorator, or as a wrapper: extendSchema({...})(fn). On a class it applies to every method.

import { extendSchema, ModelViewSet, action, type APIRequest } from '@ghuri/rest'
export class PostViewSet extends ModelViewSet<Post> {
@extendSchema({
summary: 'Publish a post',
description: 'Marks the post as published. Idempotent.',
request: null,
responses: { 200: { type: 'object', properties: { status: { type: 'string' } } } },
tags: ['posts'],
})
@action({ detail: true, methods: ['post'] })
async publish(request: APIRequest) { ... }
}

extendSchema options: operationId, summary, description, tags, deprecated, exclude, request (a serializer class or instance, a JSON Schema, or null for no body), responses (a serializer or schema, or a map such as { 200: PublishResultSerializer, 404: null }), parameters (extra OpenAPI parameter objects) and extensions (merged into the operation last).

For a whole view, set schema to an AutoSchema:

import { AutoSchema } from '@ghuri/rest'
export class PostViewSet extends ModelViewSet<Post> {
schema = new AutoSchema({ tags: ['blog'], operationIdBase: 'BlogPost', componentName: 'BlogPost' })
}

schema = null leaves a view out, as does @extendSchema({ exclude: true }) on one operation. Subclass AutoSchema (and set it as DEFAULT_SCHEMA_CLASS) to change the generation itself. Plain function views registered with path() are not API views and are left out. To document one, wrap it with apiView().

For changes to the whole document (extra tags, vendor extensions), subclass SchemaView and post-process the result of generate():

class BlogSchemaView extends SchemaView {
override generate() {
const doc = super.generate()
return { ...doc, 'x-logo': { url: '/static/logo.svg' } }
}
}

The generator is built on the same introspection API the agents package uses: router.registry for routes and actions (see Routers), and serializer.jsonSchema() for shapes. If you write your own tooling (a typed SDK generator, a contract test), start there rather than parsing the OpenAPI document. getEndpoints(patterns) and SchemaGenerator are exported for lower-level access.