Next OpenAPI

OpenAPI module for NextJS. Documenting your API by TypeScript

Disclaimer

This lib is in the prototype stage.

If you like it, start some issues and I will work on it in my free time.

If you like it and want to contribute, pull requests are always welcome.

Motivation

Next.js enables you to create full-stack Web applications

However, in most of my projects, NextJS is only used as a frontend framework, "React with SSR"

One of the issue is the lacks of support for API documentations.

Without proper API documentations, communication between BE developers and FE developers would be harder, leading to the general choice of using another full fetched BE framework.

This library is my take at resolving this issue while learning about the TypeScript compiler works.

Getting started

$ npm install next-openapi

Currently, the lib only support App Router,

1. Create a new GET API in your project folder to serve the json

# app/api/docs/json/route.ts

import { nextOpenapi } from '@next-openapi/next-openapi';
import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json(await nextOpenapi({ root: 'src/api' }));
}

This will generate an OpenAPI JSON at the declared route

2. Use any OpenAPI documentation compatible libs for visualizing. In the example project, I used redoc-try-it-out to visualize the documentation

'use client';
import { useEffect } from 'react';
import { RedocTryItOut } from '../../../../../libs/redoc-try-it-out-main/src/module';

export default function ApiDocs() {
  useEffect(() => {
    RedocTryItOut.init(
      '/api/docs/json',
      {
        tryItOutEnabled: true,
        authBtn: {
          posSelector: '#section\\/Authentication > div:first-child',
          text: 'Authorizations config',
        },
      },
      document.getElementById('redoc_container') ?? undefined
    );
  }, []);
  return <div id="redoc_container"></div>;
}

3. Wrap your request and response with provided types (more information in the examples folder)

export async function POST(
  request: NextTypedRequest<PostDocsRequestParams>
): Promise<
  | NextTypedResponse<PostDocsResponse>
  | NextTypedResponse<unknown, HttpStatusCode.ImATeapot>
> {
  return NextResponse.json({ message: 'OK' });
}

Configuration

The function nextOpenapi(config: Config) accept a config object as first parameter

Config

| Name | Type | Description | Is required | | ----------- | :--------------------------------------------: | --------------------------------: | ----------: | | root | string | API root folder | true | | title | string | OpenAPI documentation title | | description | string | OpenAPI documentation description | | version | string | API version | | tagGroups | TagGroupDefinition[] | $1 | | security | Record<string, OpenAPIV3.SecuritySchemeObject> | $1 | | servers | ServerDefinition[] | $1 |

TagGroupDefinition

| Name | Type | Description | Is required | | ----- | :------: | ----------------: | ----------: | | title | string | Group title | true | | tags | string[] | Tags in the group | true |

OpenAPIV3.SecuritySchemeObject

Basically, authentication methods that will be used in your API, and typically can be configured from your documentation UI (eg: Redoc) You can select none, one or more of the below key:

{
  BasicAuth: {
    type: 'http',
    scheme: 'basic',
  },
  BearerAuth: {
    type: 'http',
    scheme: 'bearer',
  },
  ApiKeyAuth: {
    type: 'apiKey',
    in: 'header',
    name: 'X-API-Key',
  },
}

ServerDefinition

| Name | Type | Description | Is required | | ----------- | :----: | -----------------: | ----------: | | url | string | Server url | true | | description | string | Server description | true |

Development

For NextJS App Router

yarn nx run app-router:serve

For NextJS Page Router

yarn nx run app-router:serve

Todo

[ ] Supporting path parameters

[ ] Page router supports

[ ] Code clean up