unplugin-openapi

A bundler agnostic plugin which converts OpenAPI 3.0, 3.1 and Swagger files to ESM modules.

• 💡 Support for $ref references!
• 🤖 YAML and JSON support!
• 📋 OpenAPI version 3.0, 3.1 and 2.0 (Swagger)
• 📦 Bundler agnostic! Works with Vite, Rollup, Rolldown, esbuild, Rspack, Astro and Webpack!

Install

Using npm:

npm install @zauni/unplugin-openapi --save-dev

Usage

Configure the bundler

// vite.config.ts
import openapi from '@zauni/unplugin-openapi/vite'

export default defineConfig({
  plugins: [
    openapi(),
  ],
})

// rollup.config.js
import openapi from '@zauni/unplugin-openapi/rollup'

export default {
  plugins: [
    openapi(),
  ],
}

// rolldown.config.js
import openapi from '@zauni/unplugin-openapi/rolldown'

export default {
  plugins: [
    openapi(),
  ],
}

// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('@zauni/unplugin-openapi/webpack')()
  ]
}

// rspack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('@zauni/unplugin-openapi/rspack')()
  ]
}

// vue.config.js
module.exports = {
  configureWebpack: {
    plugins: [
      require('@zauni/unplugin-openapi/webpack')(),
    ],
  },
}

// esbuild.config.js
import { build } from 'esbuild'
import openapi from '@zauni/unplugin-openapi/esbuild'

build({
  plugins: [openapi()],
})

// astro.config.mjs
import { defineConfig } from 'astro/config';
import openapi from '@zauni/unplugin-openapi/astro'

export default defineConfig({
  integrations: [
    openapi(),
  ],
})

Use

With an accompanying file src/index.js, the local src/api.yaml file would now be importable as seen below:

src/api.yaml

openapi: '3.0.0'
info:
  title: My great API
  description: Great description
  version: '1.0.0'

paths:
  /my/path:
    get:
      summary: Some GET request
      responses:
        '200':
          description: Some response
          content:
            application/json:
              schema:
                type: object
                properties:
                  someKey:
                    type: string
              example:
                someKey: some value

src/index.js

import api from "./api.yaml";

console.log(api);

If you have SwaggerUI in the React flavor installed you can now render it.

src/index.jsx

import React from "react";
import ReactDOM from "react-dom";
import SwaggerUI from "swagger-ui-react";
import "swagger-ui-react/swagger-ui.css";

import api from "./api.yaml";

ReactDOM.render(<SwaggerUI spec={api} />, document.getElementById("root"));

Use with TypeScript

If you use TypeScript you need to create a file like yaml.d.ts with the following contents:

src/yaml.d.ts

/// <reference types="@zauni/unplugin-openapi/yaml" />

src/index.ts

import api from "./api.yaml";

console.log(api);

Otherwise TypeScript will fail with the error Cannot find module './api.yaml' or its corresponding type declarations.

Options

exclude

Type: String | Array[...String]
Default: null

A picomatch pattern, or array of patterns, which specifies the files in the build the plugin should ignore. By default no files are ignored.

include

Type: String | Array[...String]
Default: null

A picomatch pattern, or array of patterns, which specifies the files in the build the plugin should operate on. By default all files are targeted.

extensions

Type: Array[...String]
Default: [".yaml", ".yml"]

A list of extensions that the plugin should consider for OpenAPI spec files. By default we use YAML, but it can be extended to also use JSON file extensions like .openapi.json to distinguish the OpenAPI specs from other JSON files.

If you use TypeScript and want to use JSON files, be sure to also set the compilerOptions.resolveJsonModule to true in your tsconfig.json.

Meta

LICENSE (MIT)