API Documentation (OpenAPI and Postman)

Wappi generates OpenAPI documentation for your API automatically. Every time you start the dev server it writes two OpenAPI 3.0 spec files: an Internal spec with every endpoint and a Public spec with only the endpoints you mark as public. You can import either file into Postman, or view it in the Wappi OpenAPI documentation app.

When the docs are generated

The docs are generated by wappi run. After the server is built, Wappi creates the Internal spec, then the Public spec, then starts the dev server. There is no separate command for it.

1npx wappi run

You will see these lines in the output:

1Internal OpenAPI Documentation Complete
2Public OpenAPI Documentation Complete

The specs are created once when wappi run starts. Code changes picked up while it is running don't regenerate them, so restart wappi run to refresh the docs.

Output files

Both files are written to your project root (the folder you run wappi from). The file name starts with the name in your package.json:

1<package name>-Internal-openAPI-spec.json
2<package name>-Public-openAPI-spec.json

For example, a project named connect_api gets connect_api-Internal-openAPI-spec.json and connect_api-Public-openAPI-spec.json.

The spec's info.title is the level plus the serviceDescription from wappi.json (e.g. Internal API for my awesome App). info.description and info.version come from package.json.

Public vs Internal (private) docs

Which spec an endpoint appears in depends on API/index.ts:

1// API/index.ts
2exports.PublicApiEndpoint = {
3  Core_TestNoAuthentication_1_0_0: true,
4  // NewPublicApiEndpointGoesHere
5}

When you create an endpoint with npx wappi c, Wappi asks "Will this endpoint be in the public OpenAPI documentation?". Answer yes and it adds the endpoint to exports.PublicApiEndpoint for you. To change it later, add or remove the endpoint's line in that object. LoginRequired doesn't decide which spec an endpoint is in. Keep the // New...GoesHere comments, because the CLI uses them to insert new endpoints.

A health check entry (GET /healthcheck) is added to both specs.

Where each endpoint's docs come from

Every endpoint created with the CLI already has the files the generator reads:

1API/User/GetUserData/1.0.0/
2  README.md             // endpoint description
3  types.ts              // EndPointBody, SuccessResponse, ErrorResponse
4  _data/successData.ts  // optional docExample for the request data

Every interface in types.ts is converted to a JSON schema. Optional properties (?) are not required, and references to other interfaces in the same file are linked. If types.ts uses WappiBaseAuthenticatedBody, the request gets an auth field set to {{AuthKey}}.

Adding an example

The template's _data/successData.ts has a commented-out docExample. Uncomment it and fill it in with literal values (strings, numbers, booleans, null, objects and arrays):

1// docExample will be added to the openAPI generated documentation as - data: {...docExample}
2const docExample = {
3  userId: 'abc123',
4}

Without a docExample, Wappi builds the example from the schema with empty values ('', 0, false).

What the request looks like in the spec

Each endpoint version is listed as a POST at /<Namespace>/<EndpointName>/<x.y.z>. Its example request body uses the Wappi request format:

1{
2  "name": "User GetUserData",
3  "version": "1.0.0",
4  "query": "User_GetUserData",
5  "data": { ...docExample },
6  "results": { "name": "results" },
7  "auth": "{{AuthKey}}"   // only for endpoints that require auth
8}

The server URL is {{baseUrl}}, described in the spec as the main API server where the query field decides which endpoint is called.

Import into Postman

In Postman, choose Import and select one of the generated -openAPI-spec.json files. The spec uses {{baseUrl}} and {{AuthKey}} placeholders, so set baseUrl (for example http://localhost:3030 locally) and AuthKey as Postman variables. Share the Public spec with external API users and keep the Internal spec for your own team.

View the docs in a website

The Wappi OpenAPI documentation app is a Next.js site that renders a spec as browsable API docs, with endpoint details, search and code snippets. It reads the spec from public/openapi-spec.json and serves it to the pages through /api/openapi-spec. To use it, copy the spec you want to publish (usually the Public one) into public/openapi-spec.json, then run or deploy the app:

1cp connect_api-Public-openAPI-spec.json <docs-app>/public/openapi-spec.json
2cd <docs-app>
3pnpm dev   # runs on port 3011

Related

See Namespaces for the folder structure, CLI Commands for wappi run, and Auth Keys for logging in.