Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tazo90/next-openapi-gen
Super fast and easy way to generate OpenAPI documentation automatically from API routes in a NextJS 14
https://github.com/tazo90/next-openapi-gen
api docs nextjs openapi react redoc swagger
Last synced: 20 days ago
JSON representation
Super fast and easy way to generate OpenAPI documentation automatically from API routes in a NextJS 14
- Host: GitHub
- URL: https://github.com/tazo90/next-openapi-gen
- Owner: tazo90
- Created: 2024-10-05T07:13:48.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2024-10-23T23:03:30.000Z (23 days ago)
- Last Synced: 2024-10-24T12:24:14.453Z (23 days ago)
- Topics: api, docs, nextjs, openapi, react, redoc, swagger
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/next-openapi-gen
- Size: 6.36 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# next-openapi-gen
**next-openapi-gen** super fast and easy way to generate OpenAPI 3.0 documentation automatically from API routes in a Next.js 14.
With support for multiple user interfaces next-openapi-gen makes documenting your API a breeze!
## Prerequisites
- Nextjs >= 14
- Node >= 18
## Supported interfaces
- Swagger
- Redoc
- Stoplight Elements
- RapiDoc
## Features
- **Automatic OpenAPI Generation**: Generate OpenAPI 3.0 documentation from your Next.js routes, automatically parsing TypeScript types for parameters, request bodies and responses.
- **TypeScript Type Scanning**: Automatically resolve TypeScript types for params, body, and responses based on your API endpoint's TypeScript definitions. Field comments in TypeScript types are reflected as descriptions in the OpenAPI schema.
- **JSDoc-Based Documentation (Optional)**: Document API routes with JSDoc comments, including tags like `@openapi`, `@auth`, `@desc`, `@params`, `@body`, and `@response` to easily define route metadata.
- **UI Interface Options**: Choose between `Swagger UI`, `Redoc`, `Stoplight Elements` or `RapiDoc` to visualize your API documentation. Customize the interface to fit your preferences.
- **Real-time Documentation**: As your API evolves, regenerate the OpenAPI documentation with a single command, ensuring your documentation is always up to date.
- **Easy configuration**: Customize generator behavior using the `next.openapi.json` configuration file, allowing for quick adjustments without modifying the code.
## Installation
```bash
yarn add next-openapi-gen
```
## Usage
### Step 1: Initialize Configuration and Setup
Run the following command to generate the `next.openapi.json` configuration file and automatically set up Swagger UI with `/api-docs` routes:
```bash
npx next-openapi-gen init --ui swagger --docs-url api-docs
```
Parameters:
- **ui**: `swagger` | `redoc` | `stoplight` | `rapidoc`
- **docs-url**: url on which api docs will be visible
This command does the following:
- Generates a `next.openapi.json` file, which stores the OpenAPI configuration for your project.
- Installs Swagger UI to provide an API documentation interface.
- Adds an `/api-docs` route in the Next.js app for visualizing the generated OpenAPI documentation.
### Step 2: Add JSDoc Comments to Your API Routes
Annotate your API routes using JSDoc comments. Here's an example:
```typescript
//app/api/auth/reset-password/route.ts
import { type NextRequest } from "next/server";
type ResetPasswordParams = {
token: string; // Token for resetting the password
};
type ResetPasswordBody = {
password: string; // The new password for the user
};
type ResetPasswordResponse = {
message: string; // Confirmation message that password has been reset
};
/**
* Reset the user's password.
* @auth: bearer
* @desc: Allows users to reset their password using a reset token.
* @params: ResetPasswordParams
* @body: ResetPasswordBody
* @response: ResetPasswordResponse
*/
export async function POST(req: Request) {
const searchParams = req.nextUrl.searchParams;
const token = searchParams.get("token"); // Token from query params
const { password } = await req.json(); // New password from request body
// Logic to reset the user's password
return Response.json({ message: "Password has been reset" });
}
```
- `@openapi`: Marks the route for inclusion in the OpenAPI specification.
- `@auth`: Specifies authentication type used for API route (`basic`, `bearer`, `apikey`)
- `@desc`: Provides a detailed description of the API route.
- `@params`: Specifies the TypeScript interface for the query parameters.
- `@body`: Specifies the TypeScript interface for the request body.
- `@response`: Specifies the TypeScript interface for the response.
### Step 3: Generate the OpenAPI Specification
Run the following command to generate the OpenAPI schema based on your API routes:
```bash
npx next-openapi-gen generate
```
This command processes all your API routes, extracts the necessary information from JSDoc comments, and generates the OpenAPI schema, typically saved to a `swagger.json` file in the `public` folder.
### Step 4: View API Documentation
With the `/api-docs` route generated from the init command, you can now access your API documentation through Swagger UI by navigating to `http://localhost:3000/api-docs`.
## Configuration Options
The `next.openapi.json` file allows you to configure the behavior of the OpenAPI generator, including options such as:
- **apiDir**: (default: `./src/app/api`) The directory where your API routes are stored.
- **schemaDir**: (default: `./src`) The directory where your schema definitions are stored.
- **docsUrl**: (default: `./api-docs`) Route where OpenAPI UI is available.
- **ui**: (default: `swagger`) OpenAPI UI interface.
- **outputFile**: (default: `./swagger.json`) The file where the generated OpenAPI specification will be saved in `public` folder.
- **includeOpenApiRoutes**: (default: `false`) When `true`, the generator will only include routes that have the `@openapi` tag in their JSDoc comments.
## Interface providers
SwaggerUI
Redoc
Stoplight Elements
RapiDoc
