Create Swagger document on NEXT.JS

Under NEXTJS V14

3 min readDec 20, 2023

Create swagger document as known as OpenAPI Specification for description how to interactive with APIs would be widely used all over the world. NEXT.JS introduced server component(s) that take advantage for programmer to develop APIs in seamless way.

The story would talk about how to adapt 3rd party library “next-swagger-doc” to NEXT.JS project from development phase to production environment.

We could follow the guide from the official Gitgub page. First we have to declare the specification/settings for the swagger definition.

// ../
import { createSwaggerSpec } from 'next-swagger-doc'

export const getApiDocs = async () => {
  const spec = createSwaggerSpec({
    // api path something might looks like './**/api'
    apiFolder: process.env.SWAGGER_API_DOC_PATH, 
    definition: {
      openapi: '3.0.0',
      info: {
        title: 'API Doc',
        version: '1.0',
      },
      security: [],
    },
  })
  return spec
}

And then created component for rendering swagger user interface:

// ../doc/api-doc.tsx
'use client';

import 'swagger-ui-react/swagger-ui.css'
import SwaggerUI from 'swagger-ui-react'


type Props = {
  spec: Record<string, any>,
  url: string | undefined
}

function ReactSwagger({ spec, url }: Props) {
  if (process.env.NODE_ENV === 'development') {
    return <SwaggerUI spec={spec} />
  }
  
  else {
    return <SwaggerUI url={url} />
  }
}

export default ReactSwagger

Final, created a route page for NEXTJS to access your swagger page:

// ../doc/page.tsx
import { getApiDocs } from '@/lib/swagger'
import ReactSwagger from './api-doc'

export default async function IndexPage() {
  const spec = await getApiDocs();
  return (
    <div className='pt-6'>
      <section className='container'>
        <ReactSwagger spec={spec} url='/swagger.json' />
      </section>
    </div>
  )
}

Something need to mention here. For the local development, we shall have no issue to build our swagger API documents through function ‘getApiDocs()’. But while we deploy to online (production) environment, Vercel. we have problem to create our swagger API documents this moment. Every time we launched our documents page we just return nothing:

And the issue we might guess that while the cloud base like Vercel that transform the API pages to SSR (Server Site Rendering) so the function could not locate the API folder path anymore.

So we need to grab our swagger document in another way. The ideal was to generate the swagger documents in statistics file then bring it together with our source to cloud. Below was the command we could generate the desired document in JSON format.

yarn next-swagger-doc-cli next-swagger-doc.json

If could also add build command inside your development settings. If you are under Vercel as well:)

The next tricky point would be we modified a little code base that if we are not in development environment then we just ask application to find the swagger data source from our pre-generation JSON file. More detail you could refer to above code snippets: api-doc.tsx & page.tsx.

Hope this story could help anyone that having same problem for creating their Swagger (OpenAPI) documents:). Please also note that if you do not expected to disclosure your API details in public, you should considerate to put them in private and also protected your APIs with tokens.

Create Swagger document on NEXT.JS

Under NEXTJS V14

Reference

Written by LAI TOCA