Cẩm nang NQDEV
HomeCheat SheetsContact
Công nghệ
Công nghệ
  • Introduction
  • Developer Roadmaps
    • Developer Roadmaps: Mô tả chi tiết
    • Roadmaps: ASP.NET Core Developer
    • Bảng phân loại cấp độ nhà phát triển .NET
    • ClearPath cho Team .NET Core
  • DotNET
    • ASP.NET Core
      • Hướng dẫn sử dụng tệp .http trong Visual Studio 2022 để thực hiện HTTP Requests
    • Message Queue
      • ZeroMQ
        • Xây dựng ZeroMQ Server trong dotNET 8 với CSharp
    • Playwright
      • Playwright: Tự Động Hóa Trình Duyệt Hiệu Quả
    • Optimize
      • Optimize - Một số cách tối ưu code và performance CSharp
    • Dev Blogs
      • Versions of .NET
        • Cập nhật từ .NET 9 lên .NET 10: Những thay đổi quan trọng
      • ASP.NET Core Web API với ASP.NET Core Web API (Native AOT): Bạn nên chọn loại nào?
      • Hướng dẫn xây dựng ứng dụng multi-tenant với .NET Core và MongoDB
      • Kiến Trúc Monolithic và Microservices: Lựa Chọn Phù Hợp Cho Dự Án Của Bạn
  • Design Patterns
    • CQRS Pattern
      • CQRS and MediatR trong .NET Core
    • Microservices
      • Ocelot
  • SQL Server
    • SQL Server Basics
    • SQL Server: DBCC
      • DBCC
      • DBCC SHOW_STATISTICS
      • DBCC SHRINKDATABASE
      • DBCC SHRINKFILE
      • DBCC SQLPERF
      • DBCC FREEPROCCACHE
    • SQL Server Replication
      • Giới thiệu SQL Server Replication
      • Hướng dẫn cấu hình và quản lý SQL Server Replication với Distribution Agent
    • SQL Server: Tập lệnh
      • SQL Server: Tập lệnh để tìm tất cả các giá trị Mặc định với Cột
    • Bảng tạm và sự linh hoạt trong xử lý dữ liệu lớn
    • Các bước để thay đổi nơi lưu trữ tệp log trong SQL Server
    • Các bước di chuyển tệp log trong SQL Server
    • Query Store trong SQL Server - Tổng Quan và Cách Quản Lý Hiệu Quả
    • SQL Server: Error Code
      • SQL Server Error : 14151, Severity: 18. Replication agent
  • Caching
    • Phân tích các phương pháp Caching dữ liệu trong .NET Core và .NET Framework
    • Redis
      • Redis mất dữ liệu khi restart
    • Varnish Cache
      • Hướng Dẫn Cài Đặt Varnish Cache với HAProxy Sử Dụng Docker Compose
  • NodeJS
    • NextJS
      • Hướng dẫn NextJS cho người mới bắt đầu
      • Parallel Routes trong Next.js
      • Hướng dẫn cấu hình Swagger trong NextJS
    • ReactJS
      • Hiểu về hook useRef của React như thế nào cho đúng
      • Tìm hiểu sâu hơn về useEffect từ A-Z
  • OS Linux
    • Tập lệnh Linux hay dùng
    • Centos 7
      • Hướng dẫn cài đặt và cấu hình Centos 7 dành cho người mới bắt đầu
      • Hướng Dẫn Kiểm Tra Các Cổng Đang Mở Trên Hệ Thống CentOS
      • Hướng Dẫn Sử Dụng zip Trên CentOS
      • Hướng dẫn cấu hình iptables để mở tất cả các cổng cho IP private
    • Windows
      • Hướng dẫn quản lý ứng dụng khởi động Windows bằng Registry Editor
  • VMware
    • Cách ảo hóa macOS Sierra trong VMWare Windows 10
    • Tự tin làm chủ mạng lưới: Cẩm nang tính toán địa chỉ IP từ A đến Z
  • Docker
    • Getting Started with Docker
    • Docker HUB
      • nqdev/nginx
  • Templates
    • Tabler Admin Template: Xây dựng Dashboard Quản trị đẹp mắt và dễ dàng
  • Open Source
    • shadcn-ui/ui
    • Kuma UI
    • Midone
  • Ứng dụng
    • Ansible
      • Ansible: Giới thiệu
      • Hướng dẫn chi tiết cài đặt Ansible
    • Apache JMeter
      • Features
        • Hướng dẫn chi tiết về Test Plan trong JMeter
        • Hướng dẫn chi tiết về Thread Group trong JMeter
    • DocFX
      • Những khái niệm cơ bản trong DocFX
      • DocFX - Hướng dẫn cài đặt, cấu hình sử dụng
      • DocFX - Hướng dẫn Markdown
      • DocFX - Hướng dẫn cấu hình file docfx.json
      • DocFX - Hướng dẫn sử dụng và tùy chỉnh Template
    • ETL Tools
      • Công cụ ETL Tools List & Software
      • Airbyte
        • Docker Compose
    • Elasticsearch
      • _reindex
        • Tìm hiểu sâu về API _reindex trong Elasticsearch
        • Hướng dẫn di chuyển dữ liệu trong Elasticsearch sử dụng API _reindex
      • _transform
    • HAProxy
      • HAProxy - Lập trình Lua và tích hợp Redis
    • Localtunnel
      • Hướng dẫn sử dụng Localtunnel để đưa ứng dụng Local lên Internet
    • LoopBack
      • Hướng dẫn cài đặt LoopBack 4 và khởi tạo dự án đầu tiên
    • N8N
      • Hướng dẫn cài đặt n8n bằng docker compose
    • NGINX Plus
      • NGINX: Hiệu suất vượt trội và giải pháp tối ưu cho hệ thống web
      • NGINX: Hướng dẫn chi tiết sử dụng GeoIP2 trên Alpine
      • NGINX: Hướng dẫn sử dụng Lua trên Alpine
      • NGINX: Hướng Dẫn Chi Tiết Cấu Hình Load Balancer
      • NGINX: Hướng Dẫn Sử Dụng Dynamic Modules
      • NGINX: Hướng dẫn Cài đặt và Sử dụng Module njs
      • Tích Hợp NGINX Làm API Gateway với Các Bước Xử Lý Phổ Biến
    • NTP - Secure Timeserver
      • Hướng dẫn cài đặt NTP an toàn với Docker Compose
    • Playwright
      • Playwright: Tự Động Hóa Trình Duyệt Hiệu Quả
    • Wordpress
      • Cách dùng Docker để phát triển ứng dụng Wordpress
  • Tin tức
    • DevSecOps là gì?
    • Giới thiệu bộ công cụ hỗ trợ lập trình từ SmallDev.tools và Code Beautify
    • Giới Thiệu và Hướng Dẫn Về DuckDB
    • Giới thiệu về Các Loại Cơ Sở Dữ Liệu
      • 1. HSQLDB (HyperSQL Database)
    • Hệ thống phân giải tên miền (DNS) và các loại bản ghi
    • Giải thích về Tiền Tố Path Nổi Tiếng – /.well-known
    • Giải mã Hệ thống tạo mã OTP của Google Authenticator
    • Quishing là gì? Hiểu và phòng tránh lừa đảo qua mã QR
  • Hướng dẫn
    • Hướng dẫn chi tiết tạo tài khoản Google bằng email công ty
    • Top 10 ASP .NET Open Source Projects GitHub 2024
    • Free Themes and Templates from Creative Tim
    • Hướng dẫn sử dụng Voler và Mazer Dashboard từ Zuramai
  • So Sánh
    • So Sánh Apache Parquet và CSV: Bảng So Sánh Chi Tiết, Ưu và Nhược Điểm
    • So Sánh Varnish Cache, Memcached và Redis: Ba Công Cụ Caching Phổ Biến trong Tối Ưu Hóa Hiệu Suất
  • Affiliate
    • Tuyển dụng
      • Bộ câu hỏi phỏng vấn T-SQL – Đánh giá ứng viên hiệu quả
    • eSMSvn: Chăm sóc khách hàng hiệu quả với SMS và ZNS
    • eSMS.vn: Giải pháp SMS Marketing hiệu quả cùng các chương trình ưu đãi hấp dẫn
Powered by GitBook
On this page
  • 1. Mục tiêu
  • 2. Cài đặt các thư viện cần thiết
  • 3. Tạo API Route để trả về Swagger JSON
  • 4. Tạo trang Swagger UI để hiển thị tài liệu API
  • 5. Tắt Layout cho trang Swagger
  • 6. Thêm các Comment JSDoc vào API Route
  • 7. Truy cập Swagger UI
  • 8. Tóm tắt

Was this helpful?

  1. NodeJS
  2. NextJS

Hướng dẫn cấu hình Swagger trong NextJS

Swagger là một công cụ mạnh mẽ giúp tự động tạo tài liệu API và cung cấp giao diện thử nghiệm API một cách trực quan. Trong bài viết này, chúng ta sẽ tìm hiểu cách cấu hình Swagger trong Next.js để hiển thị tài liệu API cho ứng dụng của bạn.

1. Mục tiêu

  • Cấu hình Swagger cho API: Tạo tài liệu API từ các route API trong ứng dụng Next.js.

  • Hiển thị Swagger UI: Sử dụng Swagger UI để hiển thị tài liệu API dưới dạng giao diện người dùng.

  • Cấu hình linh hoạt: Cho phép loại bỏ layout mặc định cho trang Swagger riêng biệt.

2. Cài đặt các thư viện cần thiết

Trước tiên, chúng ta cần cài đặt các thư viện hỗ trợ Swagger:

npm install swagger-jsdoc swagger-ui-dist
npm install @types/swagger-jsdoc @types/swagger-ui-dist --save-dev
  • swagger-jsdoc: Tự động tạo tài liệu Swagger từ mã nguồn API.

  • swagger-ui-dist: Hiển thị giao diện Swagger UI trong ứng dụng.

3. Tạo API Route để trả về Swagger JSON

Chúng ta cần tạo một API route để trả về tài liệu Swagger dưới dạng JSON, giúp Swagger UI hiển thị thông tin về các endpoint API.

Tạo file pages/api/swagger.ts:

import { NextApiRequest, NextApiResponse } from 'next';
import swaggerJSDoc from 'swagger-jsdoc';

const swaggerDefinition = {
  openapi: '3.0.0',
  info: {
    title: 'My API',
    version: '1.0.0',
    description: 'API documentation for My App',
  },
  servers: [
    { url: 'http://localhost:3000' },
  ],
};

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

const swaggerSpec = swaggerJSDoc(options);

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'GET') {
    res.status(200).json(swaggerSpec);
  } else {
    res.status(405).json({ message: 'Method Not Allowed' });
  }
}

4. Tạo trang Swagger UI để hiển thị tài liệu API

Tiếp theo, chúng ta tạo một trang riêng biệt để hiển thị Swagger UI.

Tạo file pages/swagger.tsx:

'use client';
import { useEffect } from 'react';
import SwaggerUI from 'swagger-ui-dist/swagger-ui-bundle';
import 'swagger-ui-dist/swagger-ui.css';

export const metadata = {
  title: 'Swagger UI - My API',
  description: 'API documentation for My App',
};

export default function SwaggerPage() {
  useEffect(() => {
    SwaggerUI({
      dom_id: '#swagger-ui',
      url: '/api/swagger',
      deepLinking: true,
      presets: [SwaggerUI.presets.apis],
    });
  }, []);

  return (
    <div>
      <h1>Swagger API Documentation</h1>
      <div id="swagger-ui"></div>
    </div>
  );
}

5. Tắt Layout cho trang Swagger

Để tránh layout mặc định ảnh hưởng đến Swagger UI, bạn có thể điều chỉnh trong app/layout.tsx:

import { ReactNode } from 'react';
import { usePathname } from 'next/navigation';

export default function Layout({ children }: { children: ReactNode }) {
  const pathname = usePathname();
  if (pathname === '/swagger') {
    return <>{children}</>;
  }
  return (
    <html lang="en">
      <body>
        <header>
          <h1>My App Header</h1>
        </header>
        <main>{children}</main>
        <footer>Footer Content</footer>
      </body>
    </html>
  );
}

6. Thêm các Comment JSDoc vào API Route

Swagger sử dụng JSDoc để tự động tạo tài liệu API. Hãy thêm comment vào các API route của bạn như sau:

import { NextApiRequest, NextApiResponse } from 'next';

/**
 * @openapi
 * /api/users:
 *   get:
 *     description: Returns a list of users
 *     responses:
 *       200:
 *         description: A list of users
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id:
 *                     type: integer
 *                   name:
 *                     type: string
 */
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const users = [
    { id: 1, name: 'John Doe' },
    { id: 2, name: 'Jane Doe' },
  ];
  res.status(200).json(users);
}

7. Truy cập Swagger UI

Sau khi hoàn thành các bước trên, bạn có thể truy cập tài liệu API tại địa chỉ:

http://localhost:3000/swagger

8. Tóm tắt

Bước

Nội dung

Cài đặt thư viện

Cài đặt swagger-jsdoc và swagger-ui-dist

Tạo API Route

Trả về tài liệu Swagger JSON

Tạo trang Swagger UI

Hiển thị tài liệu API với Swagger UI

Tắt layout cho trang Swagger

Đảm bảo Swagger UI hiển thị độc lập

Thêm Comment JSDoc

Giúp Swagger tự động tạo tài liệu API

Với các bước trên, bạn đã có một hệ thống Swagger UI hoàn chỉnh trong Next.js để tài liệu hóa và thử nghiệm API của mình một cách dễ dàng. Chúc bạn thành công!

PreviousParallel Routes trong Next.jsNextReactJS

Last updated 3 months ago

Was this helpful?