---
title: OpenAPI and client generators
description: Your app's API as an OpenAPI 3.1 document, and how to get typed clients, docs and tests from it in any language.
section: Data
order: 5
---

# OpenAPI and client generators

<p class="lead">Every Sluurp app describes its own REST API as an OpenAPI 3.1 document. Any tool that reads OpenAPI can use it to make a typed client in your language, show interactive docs, or test the API.</p>

## The document

`GET /api/openapi.json` is made from the app as it is right now:

- every collection's endpoints, with its fields as a schema and its rules written out;
- signing in, signing up and refreshing a token;
- the app's own [functions](/docs/server-functions), with their method and rule.

Because it's made on each request, it can't drift from the app. Add a field, and the document has it at once.

It describes every collection, so only a superuser may read it. Sign in as one, and pass the token:

```sh title="Terminal"
TOKEN=$(curl -s http://localhost:8090/api/collections/_superusers/auth-with-password \
  -H 'Content-Type: application/json' \
  -d '{"identity":"you@example.com","password":"…"}' | jq -r .token)

curl -s http://localhost:8090/api/openapi.json -H "Authorization: Bearer $TOKEN" > openapi.json
```

Or open the admin's **API** screen and download `openapi.json` from there. The same screen lets you try any endpoint as yourself, and copy the request as `curl`.

Save the file in your project and generate from it. Fetch it again when the schema changes, since generated code only knows what was there when you made it.

## Typed clients

### TypeScript

For a web app on Sluurp you rarely need one, since the [client](/docs/client) knows your collections already. For another codebase, [openapi-typescript](https://openapi-ts.dev) turns the document into types, and `openapi-fetch` calls the API with them:

```sh title="Terminal"
npx openapi-typescript openapi.json -o src/sluurp-api.d.ts
```

```ts title="src/api.ts"
import createClient from "openapi-fetch";
import type { paths } from "./sluurp-api";

const api = createClient<paths>({ baseUrl: "https://example.com", headers: { Authorization: `Bearer ${token}` } });
const { data } = await api.GET("/api/collections/tasks/records", { params: { query: { filter: "done = false" } } });
```

[Orval](https://orval.dev) and [Hey API](https://heyapi.dev) make clients too, including hooks for TanStack Query.

### Other languages

[OpenAPI Generator](https://openapi-generator.tech) makes clients for more than 50 languages from the same file:

```sh title="Terminal"
npx @openapitools/openapi-generator-cli generate -i openapi.json -g python -o clients/python
```

Change `-g` for other languages: `go`, `java`, `kotlin`, `swift5`, `csharp`, `dart`, `php`, `ruby` or `rust`. Tools made for one language are often nicer to use:

| Language | Tool |
|---|---|
| Python | [openapi-python-client](https://github.com/openapi-generators/openapi-python-client) |
| Go | [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen) |
| C# and .NET | [NSwag](https://github.com/RicoSuter/NSwag), or Kiota |
| Swift | [Swift OpenAPI Generator](https://github.com/apple/swift-openapi-generator) |
| Kotlin and Java | OpenAPI Generator's `kotlin` and `java` |
| Many | [Kiota](https://learn.microsoft.com/openapi/kiota/), from Microsoft |

## Docs to browse

Any OpenAPI viewer shows the file as browsable docs, with a form to try each endpoint: [Swagger UI](https://swagger.io/tools/swagger-ui/), [Redoc](https://redocly.com/redoc) or [Scalar](https://scalar.com). To look at it without installing anything, paste the file into [editor.swagger.io](https://editor.swagger.io).

The file describes your whole schema and its rules. Share it with people who build against your API, but don't publish it where anyone can read it.

## Tools that import it

- **Postman, Insomnia, Bruno and Hoppscotch** import the file as a collection of requests.
- **Schemathesis** reads it to test every endpoint with generated input, looking for crashes and answers that don't match the schema.
- **AI assistants and agents** can be given the file, so they know every endpoint and field of your app.

## Related

- [The REST API](/docs/api): every endpoint, filters, files and errors.
- [Browser client](/docs/client): the typed JavaScript client for apps on Sluurp.