nuxt-openapi-docs-module

OpenApiDocs Nuxt Module

This module provides a simple way to display OpenAPI documentation in a Nuxt.js 2 & 3 application. It allows you to define an OpenAPI specification file and renders it using a set of reusable Vue.js components.

work with static and server target

Package Version Information

Version	Supported Nuxt Version
3.0	2.x and 3.x
4.0	2.x and 3.x
5.0	3.x
5.2	> 3.7

for nuxt 3 need add vite.config.ts

import { defineConfig } from "vite";

export default defineConfig({
  build: {
    rollupOptions: {
      external: ["vue/server-renderer"],
    },
  },
});

• ✨  Release Notes
• 🛠 Demo
• 💡 Lite example

Quick Setup

1. Add nuxt-openapi-docs-module dependency to your project

npx nuxi@latest module add nuxt-openapi-docs-module

1. Add nuxt-openapi-docs-module to the modules section of nuxt.config.ts

nuxt 3

export default defineNuxtConfig({
  modules: [
    'nuxt-openapi-docs-module'
  ]
})

nuxt 2

module.exports = {
  modules: [
    'nuxt-openapi-docs-module',
  ],
}

1. create docs/openapi folder in root project dir(not src) or change path - folder parameter

2. You can use Vue Devtools "Routes" section to see new routes.

Configuration

You can customize the behavior of the module by providing options in the nuxt.config.js file.

module.exports = {
modules: [
    [
        'nuxt-openapi-docs-module',
        {
            folder: './docs/openapi',
            name: 'OpenApiDocs',
            files: function() {return { 'News-API': 'News API'}},
        }
    ],
],
// ...
}

• folder (default: ./docs/openapi): the folder where your OpenAPI specification files are located.
• name (default: OpenApiDocs): the name of the main component used to render the OpenAPI documentation.
• path: the component url for docs.
• files: function with files list in OpenApiDocs folder, files: function() {return { 'News-API': 'News API'}}.
• debug: print debug information to console, Default: false
• list: Toggling the list of documents, Default: false
• locales: array wit enabled locales, Default: ['en'] Support: ['en', 'fr', 'de', 'ru', 'ch', 'es', 'hi', 'ar', 'zh', 'pt']
• logo: svg logo in string
• footer: doc footer

Folder Structure

The default folder structure for your OpenAPI specification files should look like this:

docs/
    openapi/
        api1.yaml
        api2.yaml

Localization

Localization works together with the i18n plugin

1. Add info - x-locales

info:
  #  ...
  x-locales:
    en: English
    ru: Русский

1. Add locale text

  /pet:
    post:
      # ...
      summary: Add a new pet to the store
      x-summary-ru: Добавить нового питомца в магазин

1. add locale to i18n

//...
en: {
  welcome: 'Welcome',
  openapidoc: {
    "api_documentation": "API documentation",
    "select_route": "Select a route from the list below:",
    "info": "Info",
    "components": "Components",
    "callbacks": "Callbacks",
    "examples": "Examples",
    "media_type": "Media Type",
    "summary": "Summary",
    "content": "Content",
    "title": "Title",
    "servers": "ServersServers",
    "code_simple": "Code simple",
    "type": "Type",
    "enum": "Enum",
    "pattern": "Pattern",
    "items": "Items",
    "properties": "Properties",
    "name": "Name",
    "security": "Security",
    "security_schemes": "Security Schemes",
    "one_of": "One Of",
    "all_of": "All Of",
    "additional_properties": "Additional Properties",
    "default": "Default",
    "format": "Format",
    "deprecated": "Deprecated!",
    "value": "Value",
    "parameter_name": "Parameter Name",
    "description": "Description",
    "required": "Required",
    "schema": "Schema",
    "example": "Example",
    "request_bodies": "Request Bodies",
    "request_body": "Request Body",
    "responses": "Responses",
    "status": "Status",
    "in": "In",
    "minimum": "Minimum string length",
    "maximum": "Maximum number of items",
    "maximum_props": "Maximum number of properties",
    "minimum_props": "Minimum number of properties",
    "not": "Not",
    "bearer_format": "Bearer format",
    "authorization_url": "Authorization URL",
    "token_url": "Token URL",
    "refresh_url": "Refresh URL",
    "scopes": "Scopes",
    "content_type": "Content Type",
    "variables": "Variables"
  }
},

Example: playground2/docs/openapi/localization.yaml and playground2/nuxt.config.js

Plugin

Here's a description of all the properties and methods of the OpenApiPlugin interface:

• addParam(pos: 'headers'|'query'|'postData'|'path'|'cookie', name: string, value: string, type?: string): void This method allows you to add a parameter to the API documentation. The pos parameter specifies the position of the parameter (headers, query, postData, path, or cookie), while name and value specify the name and value of the parameter, respectively. The type parameter is optional and specifies the data type of the parameter.
• clearParams(): void This method clears all the parameters that have been added to the API documentation.
• addLocale(lang: string, locale: {[key: string]: string}): void This method allows you to add a translation for a specific language. The lang parameter specifies the language code (e.g., "en", "fr", "es"), while the locale parameter is an object that maps translation keys to their respective translations.
• setAccess(accessor: (path: string) => boolean): boolean This method sets the accessor function that determines whether the user has access to a specific file. The accessor function takes a file path as input and returns a boolean indicating whether the user has access.
• setRouteInfo(routeInfo: (file: string, url: string, method: string) => string|null): void; add route info to path

Example: example/plugins/auth.js

 context.$openapidoc.setAccess((file) => {
    return file !== 'no-access';
  })

  context.$openapidoc.setFooter('<div><b>Nuxt OpenApi doc panel</b> </div>')

Development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground with nuxt
npm run dev

# Build the playground
npm run dev:build

Custom pages

1. Create custom page, for example pages/docs/petstore_extended/:locale/custom/page1.vue

• docs - path from config (docs default)
• petstore_extended - doc name
• :locale - locale (en default)
• custom - static path
• page1 - page name

1. create vue component, for example page1.vue

<template>
  <div class="items-top min-h-screen bg-gray-100 sm:items-center sm:pt-0">
    <client-only>
      <div v-html="content"></div>
    </client-only>
    <hr>
    <div>my custom page</div>
  </div>
</template>

<script setup lang="ts">
defineI18nRoute({
  locales: ['en', 'ru'],
});

definePageMeta({
  layout: 'open-api-layout-petstore_extended',
});
</script>

where open-api-layout-petstore_extended is open-api-layout-${doc_name}

here you need to replace the page parameter to you page name

1. add custom routes to openapi specification

x-custom-path:
  title: 'Custom'
  description: 'Custom pages'
  paths:
    page1:
      title: 'Custom page 1'
      description: 'Custom pages 1'

page1 - your file name

Example playground2/docs/openapi/page.yaml

Changelog

[5.2.6] - 2024-05-05

Changed

• add docs page
• add plugin page to devtools
• add types