OpenAPI Types ​

If your API has an OpenAPI schema, nuxt-api-party can use it to generate types for you. These include path names, supported HTTP methods, request body, response body, query parameters, and headers.

Usage of this feature requires openapi-typescript to be installed. This library generates TypeScript definitions from your OpenAPI schema file.

Install it before proceeding:

pnpm add -D openapi-typescript

pnpm add -D openapi-typescript

yarn add -D openapi-typescript

yarn add -D openapi-typescript

npm install -D openapi-typescript

npm install -D openapi-typescript

Schema Generation ​

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

• NestJS
• FastAPI
• Django
• ASP.NET Core
• Spring
• Utopia

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

Configuring the schema ​

To take advantage of these type features, add the schema property to your endpoint config. It should be set to a file path or URL of the OpenAPI schema or an async function returning the parsed OpenAPI schema. The file can be in either JSON or YAML format.

The following schema will be used for the code examples on this page.

# `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:
        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
          type: number
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Foo'
components:
  schemas:
    Foo:
      type: object
      items:
        id:
          type: number
        bar:
          type: string
      required:
        - bar

# `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:
        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
          type: number
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Foo'
components:
  schemas:
    Foo:
      type: object
      items:
        id:
          type: number
        bar:
          type: string
      required:
        - bar

Reference the schema file in your endpoint config:

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

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

Using the Types ​

For most usages, no further intervention is needed. nuxt-api-party will use the types generated from this config to infer the correct types automatically when $myApi and useMyApiData is used.

However, there may be a few things you may want to do now that you have type information.

Extract the Response Body Type ​

You can get the request and response bodies directly from the exported components interface of the virtual module containing the types.

Using the schema above:

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

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

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

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

Use OpenAPI Defined Path Parameters ​

OpenAPI can define path parameters on some endpoints. They are declared as /foo/{id}. Unfortunately, the endpoint is not defined as /foo/10, so using that as the path will break type inference.

To get around this, set an object of the parameters to the property pathParams. You can then use the declared path for type inference, and the type checker will ensure you provide all required path parameters. The parameters will be interpolated into the path before the request is made.

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

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

For reactive pathParams, pass a ref or getter function instead of a plain object.

const id = ref(10)

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

const id = ref(10)

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

Route Method Overloading ​

Some routes may be overloaded with multiple HTTP methods. The typing supports this natively and chooses the type based on the method property. When the property is omitted, the typing is smart enough to know GET is the default.

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

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

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

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

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