Skip to main content
Version: 1.x

Generating API Documentation

An API is only complete when documented. Similar to the API itself, the documentation can also be derived from the ZModel.

In Part II of the guide, we've learned how to use plugins. ZenStack ships the @zenstackhq/openapi plugin to generate OpenAPI specs from the ZModel schema. Like the API handlers, the openapi plugin also supports two flavors: "rpc" and "rest".

Once the documentation is generated, it's easy to render it using tools like Swagger UI and Redocly.

🛠️ Serving API Documentation

Let's generate an OpenAPI spec for our Todo API and serve it using Swagger UI.

1. Installing Dependencies

npm install --save-dev @zenstackhq/openapi
npm install swagger-ui-express
npm install -D @types/swagger-ui-express

2. Adding OpenAPI Plugin to ZModel

schema.zmodel
plugin openapi {
provider = "@zenstackhq/openapi"
output = "todo-api.json"
title = "My Todo API"
version = "1.0.0"
flavor = "rpc"
}

Rerun generation:

npx zenstack generate

The todo-api.json file should be generated in the project root.

3. Serving the OpenAPI Spec

Add the following code to main.ts before the line of app.listen(...):

main.ts
import swaggerUI from 'swagger-ui-express';
app.use(
'/api/docs',
swaggerUI.serve,
swaggerUI.setup(require('./todo-api.json'))
);

Now, you can visit the documentation at http://localhost:3000/api/docs in a browser.

Swagger UI

Comments
Feel free to ask questions, give feedback, or report issues.

Don't Spam


You can edit/delete your comments by going directly to the discussion, clicking on the 'comments' link below