Ubuntu中Swagger文档怎样生成与查看 - 问答

在Ubuntu中生成与查看Swagger文档的常见方法

Swagger是一套用于描述、构建和文档化RESTful API的工具集，支持通过代码注解自动生成文档，并提供交互式界面测试API。以下是在Ubuntu系统中生成与查看Swagger文档的具体步骤，涵盖不同工具和场景：

一、准备工作

在生成Swagger文档前，需确保Ubuntu系统已安装Node.js和npm（Node.js包管理器），这是使用Swagger Editor、Swagger UI等工具的基础：

sudo apt update
sudo apt install -y nodejs npm

二、使用Swagger Editor生成与查看文档

Swagger Editor是一个开源的在线/离线工具，支持直接编辑Swagger YAML/JSON文件并实时预览文档效果。

1. 安装Swagger Editor

方法1：通过npm全局安装（推荐）
运行以下命令安装Swagger Editor CLI：
```
sudo npm install -g swagger-editor-cli
```

方法2：下载源码运行
从GitHub下载Swagger Editor源码，解压后进入目录：

wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.16.1.tar.gz
tar -xvf v3.16.1.tar.gz
cd swagger-editor-3.16.1

2. 启动Swagger Editor

通过npm安装的版本：
运行以下命令启动本地服务器（默认端口8080）：
```
swagger-editor
```
源码版本：
先全局安装http-server，再启动：
```
sudo npm install -g http-server
http-server -p 8080
```

3. 生成与查看文档

打开浏览器访问http://localhost:8080，进入Swagger Editor界面。
导入现有文档：点击左侧“Import File”，选择本地的swagger.yaml或swagger.json文件。
手动编辑文档：在编辑器中修改API规范（如端点路径、参数、响应等），右侧会实时显示文档预览。
保存文档：编辑完成后，点击“File”→“Save”保存为YAML/JSON文件。

三、使用Swagger UI查看生成的文档

Swagger UI是一个可视化工具，可将Swagger YAML/JSON文件渲染为交互式API文档，支持在线测试接口。

1. 安装Swagger UI

通过npm安装：
运行以下命令全局安装：
```
sudo npm install -g swagger-ui-express
```

2. 配置Swagger UI

创建一个简单的Node.js服务器，用于托管Swagger文档：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./path/to/your/swagger.json'); // 替换为你的文档路径

const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); // 挂载Swagger UI到/api-docs路径
const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Swagger UI is running at http://localhost:${PORT}/api-docs`);
});

3. 启动并查看文档

运行Node.js服务器：
```
node your-server-file.js
```
打开浏览器访问http://localhost:3000/api-docs，即可看到Swagger UI界面，包含API的所有端点、参数、响应示例等信息。

四、通过编程方式生成Swagger文档（以Go语言为例）

若项目使用Go语言开发，可使用swag工具根据代码中的注释自动生成Swagger文档。

1. 安装swag工具

在终端运行以下命令安装：

go install github.com/swaggo/swag/cmd/swag@latest

2. 添加Swagger注释

在Go代码的关键位置添加注释，描述API信息。例如：

package main

import (
	"net/http"
)

// @Summary 获取用户信息
// @Description 根据用户ID返回用户详情
// @Tags Users
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} User
// @Router /users/{id} [get]
func getUserByID(w http.ResponseWriter, r *http.Request) {
	// 业务逻辑
}

type User struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

3. 生成文档

在项目根目录运行以下命令，生成docs目录（包含swagger.json、swagger.yaml和docs.go）：
```
swag init
```
生成的文档可通过Swagger UI查看（参考第三步配置）。

五、集成到构建流程（可选）

若项目使用Maven或Gradle构建，可将Swagger Codegen集成到构建过程中，自动生成文档。

1. Maven集成

在pom.xml中添加OpenAPI Generator插件：

<build>
  <plugins>
    <plugin>
      <groupId>org.openapitools</groupId>
      <artifactId>openapi-generator-maven-plugin</artifactId>
      <version>5.2.1</version>
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
          <configuration>
            <inputSpec>${project.basedir}/src/main/resources/swagger.yaml</inputSpec>
            <generatorName>html2</generatorName>
            <output>${project.build.directory}/generated-docs</output>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

运行mvn generate-sources即可生成HTML文档。

2. Gradle集成

在build.gradle中添加OpenAPI Generator任务：

plugins {
  id 'org.openapitools.codegen' version '5.2.1'
}
openApiGenerate {
  inputSpec = file("src/main/resources/swagger.yaml").toString()
  generatorName = 'html2'
  outputDir = file("build/generated-docs")
}

运行gradle openApiGenerate生成文档。

注意事项

确保API服务运行正常，且Swagger文档路径（如/v2/api-docs或/swagger.json）可访问。
若遇到CORS问题，需在API服务中配置跨域支持（如Spring Boot中添加@CrossOrigin注解）。
根据项目语言和框架选择合适的工具（如Spring Boot推荐springdoc-openapi，Go推荐swag）。

0 赞

0 踩