OpenAPI Integration

Point an endpoint at an OpenAPI schema and the module types every request against it:

• Request path with path parameters
• Query parameters
• Headers
• Request body
• Response body
• Error responses

Mandatory Dependency

This feature generates TypeScript definitions from your OpenAPI schema with openapi-typescript v7. It is an optional peer dependency, so install it yourself:

npm install -D openapi-typescript

Schema Generation

Based on your configured routes, some web frameworks can generate an OpenAPI schema for you. Some examples include:

• NestJS
• ElysiaJS
• ASP.NET Core
• Spring
• utoipa

If your framework doesn't directly support it, there may also be an additional library that does.

Configuring the Schema

Add the schema property to your endpoint config. Set it to a file path or URL of the OpenAPI schema, or to the parsed schema object. The file can be JSON or YAML format.

The following schema is used for code examples on this page:

Details

# `schemas/myApi.yaml`
openapi: 3.0.0
info:
  title: My API
  version: 0.1.0
paths:
  /foo:
    get:
      operationId: getFoos
      responses:
        200:
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Foo'
    post:
      operationId: createFoo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Foo'
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Foo'
  /foo/{id}:
    get:
      operationId: getFoo
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: number
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Foo'
components:
  schemas:
    Foo:
      type: object
      properties:
        id:
          type: number
        bar:
          type: string
      required:
        - bar

Reference the schema file in your endpoint configuration:

nuxt.config.ts

export default defineNuxtConfig({
  apiParty: {
    endpoints: {
      myApi: {
        url: process.env.MY_API_API_BASE_URL!,
        schema: './schemas/myApi.yaml'
      }
    }
  }
})

TIP

In development, changes to a local schema file regenerate the types right away. A remote schema is read once, so pick up changes there by restarting the Nuxt dev server.

Using the Types

For most use cases, no further configuration is needed. Nuxt API Party uses the generated types to infer correct types automatically when useFetch-like and $fetch-like composables are used.

Extract Schema Types

The exported components interface of the virtual module for your API contains all schema types defined in your OpenAPI schema. Use it to extract models for your API.

Using the schema above, extract the Foo type:

import type { components } from '#nuxt-api-party/myApi'

type Foo = components['schemas']['Foo']
//   ^? { id?: number; bar: string }

Use OpenAPI Defined Path Parameters

OpenAPI can define path parameters on endpoints. They're declared as /foo/{id}. The endpoint isn't defined as /foo/10, so using that as the path breaks type inference.

To work with path parameters, set an object of parameters to the path property. Use the declared path for type inference, and the type checker ensures you provide all required path parameters. Parameters are interpolated into the path before the request is made.

const data = await $myApi('/foo/{id}', {
  path: {
    id: 10
  }
})

For reactive path parameters, pass a ref or getter function:

const id = ref(10)

const data = await $myApi('/foo/{id}', {
  path: () => ({
    id: id.value
  })
})

WARNING

Issues will NOT be reported at runtime by Nuxt API Party if the wrong parameters are used. The incomplete path will be sent to the backend as-is.

Route Method Overloading

Some routes support multiple HTTP methods. The typing chooses the type based on the method property. When omitted, typing defaults to GET.

In the example schema, GET /foo will return a Foo[] array, but POST /foo will return a Foo object.

const resultGet = await $myApi('/foo')
//    ^? { id?: number; bar: string }[]

const resultPost = await $myApi('/foo', {
//    ^? { id?: number; bar: string }
  method: 'POST',
  body: {
    bar: 'string'
  }
})

OpenAPI Type Helpers

Type Declarations

For more details and examples, see the OpenAPI Type Helpers documentation.

Beyond inferring the composables, the module generates one type per endpoint that carries everything an operation declares. It is named after the endpoint ID and takes a path and a method:

import type { MyApi } from '#nuxt-api-party'

type CreateFoo = MyApi<'/foo', 'post'>

type PathParams = CreateFoo['path'] // `never`, the operation declares none
type RequestBody = CreateFoo['request'] // { id?: number; bar: string }
type Response = CreateFoo['response'] // { id?: number; bar: string }
type ByStatus = CreateFoo['responses'] // { 200: { id?: number; bar: string } }

Extracting from the schema this way beats writing the same shape by hand, which drifts the moment the API changes.

Follow the OpenAPI Type Helpers documentation for every property the type carries.