<!-- Source: https://www.wappi.dev/api-documentation -->

# 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.

```bash
npx wappi run
```

You will see these lines in the output:

```typescript
Internal OpenAPI Documentation Complete
Public 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`:

```typescript
<package name>-Internal-openAPI-spec.json
<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`:

| Spec | Includes |
| --- | --- |
| Internal | Every endpoint version folder under API/<Namespace>/<EndpointName>/<x.y.z> |
| Public | Only endpoints set to true in exports.PublicApiEndpoint |

```typescript
// API/index.ts
exports.PublicApiEndpoint = {
  Core_TestNoAuthentication_1_0_0: true,
  // NewPublicApiEndpointGoesHere
}
```

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:

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

| Source | Used for |
| --- | --- |
| README.md | The endpoint's description, used as written |
| types.ts: EndPointBody | The schema for the request data |
| types.ts: SuccessResponse | The 200 Success response schema |
| types.ts: ErrorResponse | The 400 Error response schema |
| _data/successData.ts: docExample | The example request data, also used as schema defaults |

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):

```typescript
// docExample will be added to the openAPI generated documentation as - data: {...docExample}
const docExample = {
  userId: 'abc123',
}
```

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:

```json
{
  "name": "User GetUserData",
  "version": "1.0.0",
  "query": "User_GetUserData",
  "data": { ...docExample },
  "results": { "name": "results" },
  "auth": "{{AuthKey}}"   // only for endpoints that require auth
}
```

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:

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

## Related

See [Namespaces](https://www.wappi.dev/namespaces) for the folder structure, [CLI Commands](https://www.wappi.dev/cli-commands) for `wappi run`, and [Auth Keys](https://www.wappi.dev/security/auth-keys) for logging in.

URL: https://www.wappi.dev/api-documentation