在 Swagger 中生成 API 文檔可以通過使用 Swagger UI 或 Swagger Editor 來展示 API 的結構和詳細信息。Swagger 使用 OpenAPI 規範來描述 RESTful API,並且能夠自動生成互動式文檔。
你可以使用以下幾種方法來生成 API 文檔:
index.html
,然後在 url
中添加你的 API 的 OpenAPI/Swagger 描述文件 URL。npm install -g swagger-codegen
swagger-codegen generate -i <path_to_your_swagger.yaml> -l html2 -o ./output
這會根據你提供的 OpenAPI 文件生成 HTML 格式的 API 文檔。要生成 API 文檔,首先需要有一個 API 的 OpenAPI 描述文件。這個文件通常用 YAML 或 JSON 格式編寫,描述了 API 的端點(路徑)、HTTP 方法、參數、返回值等。
例如,這是一個簡單的 OpenAPI 規範示例:
openapi: 3.0.0
info:
title: Simple API
version: 1.0.0
paths:
/users:
get:
summary: Get 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
如果你想在代碼中自動生成 Swagger 文檔,可以根據所使用的框架選擇相應的 Swagger 庫。例如:
swagger-jsdoc
:swagger-jsdoc
和 swagger-ui-express
:
npm install swagger-jsdoc swagger-ui-express
const swaggerJsDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const express = require('express');
const app = express();
const swaggerOptions = {
swaggerDefinition: {
openapi: '3.0.0',
info: {
title: 'Simple API',
version: '1.0.0',
},
},
apis: ['./routes/*.js'], // 路由的文件位置
};
const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));
app.listen(3000, () => console.log('Server running on port 3000'));
springdoc-openapi
:pom.xml
中加入依賴:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.5.9</version>
</dependency>
http://localhost:8080/swagger-ui.html
來查看 API 文檔。在服務器端正確設置了 OpenAPI 描述文件後,Swagger UI 就可以通過讀取該文件生成可視化的 API 文檔。你可以通過設置 Swagger UI 頁面來展示文檔。
生成 API 文檔的基本步驟是: