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:

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

Usage

Configure the bundler

1// vite.config.ts
2import openapi from '@zauni/unplugin-openapi/vite'
3
4export default defineConfig({
5  plugins: [
6    openapi(),
7  ],
8})

1// rollup.config.js
2import openapi from '@zauni/unplugin-openapi/rollup'
3
4export default {
5  plugins: [
6    openapi(),
7  ],
8}

1// rolldown.config.js
2import openapi from '@zauni/unplugin-openapi/rolldown'
3
4export default {
5  plugins: [
6    openapi(),
7  ],
8}

1// webpack.config.js
2module.exports = {
3  /* ... */
4  plugins: [
5    require('@zauni/unplugin-openapi/webpack')()
6  ]
7}

1// rspack.config.js
2module.exports = {
3  /* ... */
4  plugins: [
5    require('@zauni/unplugin-openapi/rspack')()
6  ]
7}

1// vue.config.js
2module.exports = {
3  configureWebpack: {
4    plugins: [
5      require('@zauni/unplugin-openapi/webpack')(),
6    ],
7  },
8}

1// esbuild.config.js
2import { build } from 'esbuild'
3import openapi from '@zauni/unplugin-openapi/esbuild'
4
5build({
6  plugins: [openapi()],
7})

1// astro.config.mjs
2import { defineConfig } from 'astro/config';
3import openapi from '@zauni/unplugin-openapi/astro'
4
5export default defineConfig({
6  integrations: [
7    openapi(),
8  ],
9})

Use

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

src/api.yaml

1openapi: '3.0.0'
2info:
3  title: My great API
4  description: Great description
5  version: '1.0.0'
6
7paths:
8  /my/path:
9    get:
10      summary: Some GET request
11      responses:
12        '200':
13          description: Some response
14          content:
15            application/json:
16              schema:
17                type: object
18                properties:
19                  someKey:
20                    type: string
21              example:
22                someKey: some value

src/index.js

1import api from "./api.yaml";
2
3console.log(api);

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

src/index.jsx

1import React from "react";
2import ReactDOM from "react-dom";
3import SwaggerUI from "swagger-ui-react";
4import "swagger-ui-react/swagger-ui.css";
5
6import api from "./api.yaml";
7
8ReactDOM.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

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

src/index.ts

1import api from "./api.yaml";
2
3console.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)