Ubuntu Swagger API文档怎么生成 - 问答

在Ubuntu上生成Swagger API文档的常见流程

1. 准备开发环境

首先安装Node.js和npm（Node.js包管理器），这是使用Swagger工具的基础：

sudo apt update
sudo apt install -y nodejs npm

2. 安装Swagger核心工具

根据需求选择以下工具（任选其一即可）：

Swagger Editor：在线/本地编辑OpenAPI规范的工具，支持实时预览文档。
```
sudo npm install -g swagger-ui
```
Swagger Codegen：根据OpenAPI规范生成客户端/服务器代码的工具（如Java、Python等）。
```
sudo npm install -g swagger-codegen
```
swagger-jsdoc：通过代码注释自动生成OpenAPI规范的工具（适合已有代码的项目）。
```
sudo npm install -g swagger-jsdoc
```

3. 编写OpenAPI规范文件

OpenAPI规范（OAS）是Swagger文档的基础，通常为swagger.yaml或swagger.json格式。可通过以下两种方式创建：

手动编写：参考OpenAPI规范文档，定义API的基本信息（标题、版本）、路径（接口）、参数、响应等。示例（swagger.yaml）：

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: An array of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

使用Swagger Editor：下载Swagger Editor（如从官网），通过图形界面填写API信息，导出为swagger.yaml文件。

4. 生成Swagger文档

方式一：通过代码注释自动生成（适合已有项目）

若项目已有代码，可使用swagger-jsdoc从代码注释中提取API信息，生成OpenAPI规范：

swagger-jsdoc -c path/to/swagger-config.yaml -o path/to/output/swagger.json

其中，swagger-config.yaml是配置文件（定义注释解析规则），output/swagger.json是生成的规范文件。

方式二：使用Swagger Codegen生成客户端/服务器代码

若需要生成特定语言的客户端代码（如Java），可使用swagger-codegen：

swagger-codegen generate -i path/to/swagger.yaml -l java -o path/to/output/java-client

其中，-i指定输入规范文件，-l指定生成语言（如java、python），-o指定输出目录。

方式三：集成到项目中自动生成（适合开发阶段）

若使用Spring Boot等框架，可通过注解和插件自动生成文档：

添加依赖：在pom.xml（Maven）中添加Swagger依赖：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>3.0.0</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>3.0.0</version>
</dependency>

配置Swagger：创建配置类启用Swagger：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 指定Controller包
                .paths(PathSelectors.any())
                .build();
    }
}

访问文档：启动项目后，访问http://localhost:8080/swagger-ui.html即可查看交互式文档。

5. 查看与测试文档

Swagger UI：将生成的swagger.yaml/swagger.json文件导入Swagger UI（可通过swagger-ui-express或其他工具托管），通过浏览器访问查看交互式文档（支持接口测试、参数填写等功能）。
集成到项目：若使用Spring Boot，启动项目后直接访问/swagger-ui.html即可查看实时文档（文档随代码更新自动刷新）。

注意事项

确保OpenAPI规范文件符合规范（如使用正确的openapi版本、路径格式等），否则可能导致生成失败。
若使用注解方式，需在代码中正确添加Swagger注解（如@ApiOperation、@ApiParam），否则文档信息不完整。
对于大型项目，建议将Swagger集成到构建流程（如Maven/Gradle），实现文档自动生成与更新。

0 赞

0 踩