API Documentation (using Swagger)

[justindasilva]

I was wondering if there are any plans in place to build a tool that would be able to generate API Documentation automatically based on endpoints in the "routes" folder.

I'm just starting to use Nitro for the first time. It's awesome!

Usually in the past I would use a tool like SwaggerUI which would allow me to write annotations, and SwaggerUI generates a tool that allows people to view information about the API and play around with it.
I have this feeling that you can't really avoid annotations, but it would be cool if the Swagger configuration could be generated automatically based on the routes themselves.
You can infer Request type based on file name (hello.get.ts is a GET request. hello.post.ts is a POST request)
We might be able to infer available request params and response type as well based on the code.

[pi0]

Hi. Yes i plan for a generic inspector with HTTP testing UI (#3). Initially, I also created an issue for open API and swagger support (#4) but seemed to be extra effort when working on inspector. I'll reopen it to see how hard it would be.

[drewdru]

Hello, I'm not sure if this can help. I had some fun on my pet project and did something similar but I used class with decorators instead of closure for defineEventHandler cuz I didn't find a way how to get all endpoints from nitroApp or h3App.
https://github.com/drewdru/sitedrewdru/tree/nuxt3/server/utils/swagger

For validation I used Yup but I didn't find a best way how to generate OpenAPI JSON object. I tried @rudi23/yup-to-openapi but it generated an object that still needs to be normalized.

[mittci]

you do with decorators like in nestjs or express swager decorators

[mittci]

I use swagger

Page for swager

<template>
  <div>
    <swagger />
  </div>
</template>

<script setup>
import { Swagger } from '#components'

import { definePageMeta } from '#imports'

definePageMeta({
  layout: 'swagger'
})

</script>

Swagger component

  <div id="swagger-ui"></div>
</template>

<script setup lang="ts">
import { useHead } from '#imports'
import { SwaggerUIBundle, SwaggerUIStandalonePreset } from 'swagger-ui-dist'

import { onMounted } from 'vue'

useHead({
  link: [
    {
      rel: 'stylesheet',
      href: '/swagger-ui.min.css'
    }
  ]
})

onMounted(() => {
  if (process.client) {
    const config = useRuntimeConfig()
    const ui = SwaggerUIBundle({
      url: config.public.swaggerUrl,
      dom_id: '#swagger-ui',
      deepLinking: true,
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ],
      layout: 'StandaloneLayout'
    })

    window.ui = ui
  }
})
</script>

And endpoints

/**
 * @openapi
 * /api/users:
 *   get:
 *     description: 'Get all users.'
 *     responses:
 *       200:
 *         description: 'Returns users list.'
 *       404:
 *         description: 'Users was not found.'
 *       502:
 *         description: 'Internal server error.'
 *   tag: 'Users'
 */
export default defineEventHandler(async (event): Promise<Array<User> | null> => {
}

/server/api/doc.ts

/**
 * @file
 */

import { defineEventHandler } from 'h3'
import swaggerJSDoc from 'swagger-jsdoc'

export default defineEventHandler(() => {
  const swaggerDefinition = {
    openapi: '3.0.0',
    info: {
      title: 'TITLE',
      version: '1.0.0'
    },
    servers: [{ url: '/api' }],
    schemes:
      process.env.SWAGGER_SCHEMA_HTTPS === 'true'
        ? ['https']
        : ['http', 'https'],
    components: {
      securitySchemes: {
        BearerAuth: {
          type: 'apiKey',
          name: 'Authorization',
          in: 'header'
        }
      }
    },
    security: {
      ApiKeyAuth: [],
      OAuth2: {}
    }
  }

  const options = {
    swaggerDefinition,
    apis: ['server/api/**/*.ts']
  }

  return swaggerJSDoc(options)
})

I get swagger-ui.min.css from swagger package and put it in public dir.

[felixdenoix]

In the swagger component, you could also import the style from the module using the style tag instead of copying it to public:

<style src="@/node_modules/swagger-ui-dist/swagger-ui.css"></style>

[Sun-ZhenXing]

I found a new method that merges the two to incrementally add parameters.

// server/api/doc.ts
import process from 'node:process'
import { createDefu } from 'defu'
import swaggerJSDoc from 'swagger-jsdoc'
import { isArray } from 'radash'

const defu = createDefu((obj, key, value) => {
  if (key === 'tags' && isArray(value) && isArray(obj[key])) {
    obj[key] = value
    return true
  }
})

export default defineEventHandler(async () => {
  const swaggerDefinition: swaggerJSDoc.Options['swaggerDefinition'] = {
    openapi: '3.1.0',
    info: {
      title: 'OpenAPI Docs',
      version: '1.0.0',
    },
    schemes:
      process.env.SWAGGER_SCHEMA_HTTPS === 'true'
        ? ['https']
        : ['http', 'https'],
    components: {
      securitySchemes: {
        BearerAuth: {
          type: 'apiKey',
          name: 'Authorization',
          in: 'header',
        },
      },
    },
    security: {
      ApiKeyAuth: [],
      OAuth2: {},
    },
  }

  const options: swaggerJSDoc.Options = {
    swaggerDefinition,
    apis: ['server/api/**/*.ts'],
  }
  const swagger = swaggerJSDoc(options)
  const nitroReq = await fetch('http://127.0.0.1:3000/_nitro/openapi.json')
  const nitroOpenAPI = await nitroReq.json()
  return defu(swagger, nitroOpenAPI)
})

[VladimirCores]

Its not clear how to write OpenAPI specification for the specific handler. Could somebody post an example?

[TMBL-DEV]

running in to the same issue. wondering how can i specify for swagger what should be the payload of a post request to my endpoint. because currently i cant do it.

[felixdenoix]

in your route file:

...

/**
 * @openapi
 * /finalize:
 *  post:
 *    summary: update mint entity and user entity with wallet_address so that the mint can be processed
 *    requestBody:
 *      required: true
 *      content:
 *        application/json:
 *          schema:
 *            type: object
 *            properties:
 *              mintId:
 *                type: string
 *                description: the firebase id
 *              user:
 *                type: object
 *                properties:
 *                  id:
 *                    type: string
 *                    description: the firebase id
 *                  walletAddress:
 *                    type: string
 *    responses:
 *      200:
 *        content:
 *          application/json:
 *            schema:
 *              type: object
 *              properties:
 *                success:
 *                  type: boolean
 *                user:
 *                  type: object
 *                  description: the updated user
 *                  properties:
 *                    id:
 *                      type: string
 *                mint:
 *                  type: object
 *                  description: the updated mint
 *                  properties:
 *                    id:
 *                      type: string
 */
export default defineEventHandler(async (event: H3Event) => {
...

I've specified my documentation per route following the OAS@3 specification. Didn't found a way to re-use schemas across routes at the time is was using it (nov.22). Hope it helps nonetheless

[Ismael-Rakotondrazaka]

Hello
Does it works ?
I'am not be able do make it works. it ignores totally the spec; only the (dynamic) parameters is shown in the json spec.