物联网平台中的Swagger（一）介绍与基础注解使用

原创

Yeats_Liao

发布于 2025-08-31 09:30:46

1.5K0

在现代物联网平台开发中，API文档的重要性不言而喻。随着微服务架构的普及和前后端分离开发模式的广泛应用，一套完善、实时更新的API文档成为了团队协作的关键。Swagger作为目前最流行的API文档生成工具，不仅能够自动生成美观的接口文档，还提供了在线测试功能，极大地提升了开发效率。

一、OpenAPI与Swagger基础概念

1.1 OpenAPI规范介绍

OpenAPI规范（原名Swagger规范）是一个用于描述REST API的规范格式。它提供了一种标准化的方式来描述API的结构、端点、请求/响应格式、认证方式等信息。

源码：https://github.com/OAI/OpenAPI-Specification

OpenAPI规范的核心特性：

标准化描述：使用JSON或YAML格式描述API
语言无关：可以用于任何编程语言和框架
工具生态丰富：支持代码生成、文档生成、测试工具等
版本演进：从Swagger 2.0到OpenAPI 3.0的持续发展

OpenAPI规范的主要组成部分：

openapi: 3.0.0
info:
  title: 物联网平台API
  description: 提供设备管理、数据采集等功能的REST API
  version: 1.0.0
servers:
  - url: https://api.iot-platform.com/v1
paths:
  /devices:
    get:
      summary: 获取设备列表
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 成功返回设备列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
components:
  schemas:
    Device:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        status:
          type: string

1.2 Swagger生态系统介绍

Swagger是围绕OpenAPI规范构建的一套开源工具集，旨在帮助开发者设计、构建、文档化和使用REST API。

官网：https://swagger.io/

Swagger的发展历程：

2011年：Swagger项目启动，由Wordnik公司开发
2015年：Swagger规范捐赠给Linux基金会，成为OpenAPI规范
2016年：OpenAPI 3.0发布，提供更强大的功能
至今：持续发展，成为API文档的事实标准

Swagger的核心价值：

提升开发效率：自动生成文档，减少手工维护成本
改善团队协作：统一的API描述标准
降低集成成本：标准化的接口描述便于第三方集成
支持测试驱动：内置API测试功能

1.3 Swagger工具集详解

Swagger生态系统包含多个工具，每个工具都有特定的用途：

1.3.1 Swagger Editor

功能特性：

在线编辑OpenAPI规范文件
实时语法检查和验证
支持YAML和JSON格式
提供代码提示和自动补全

使用场景：

# 在Swagger Editor中编写API规范
swagger: "2.0"
info:
  title: "设备管理API"
  version: "1.0.0"
host: "api.iot-platform.com"
basePath: "/v1"
schemes:
  - "https"
paths:
  /devices:
    get:
      tags:
        - "设备管理"
      summary: "获取设备列表"
      produces:
        - "application/json"
      responses:
        200:
          description: "成功"

1.3.2 Swagger UI

功能特性：

将OpenAPI规范渲染为交互式文档
支持在线API测试
响应式设计，支持移动端
可定制主题和样式

集成方式：

<!DOCTYPE html>
<html>
<head>
  <title>API文档</title>
  <link rel="stylesheet" type="text/css" href="./swagger-ui-bundle.css" />
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="./swagger-ui-bundle.js"></script>
  <script>
    SwaggerUIBundle({
      url: './api-docs.json',
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIBundle.presets.standalone
      ]
    });
  </script>
</body>
</html>

1.3.3 Swagger Codegen

功能特性：

根据OpenAPI规范生成客户端SDK
支持40+种编程语言
生成服务器端代码框架
支持自定义模板

代码生成示例：

# 生成Java客户端
swagger-codegen generate -i api-spec.yaml -l java -o ./java-client

# 生成Python客户端
swagger-codegen generate -i api-spec.yaml -l python -o ./python-client

# 生成Spring Boot服务端代码
swagger-codegen generate -i api-spec.yaml -l spring -o ./spring-server

1.3.4 Swagger Inspector

功能特性：

API测试和调试工具
自动生成OpenAPI规范
支持团队协作
集成CI/CD流程

1.3.5 SpringFox（Java生态）

功能特性：

Spring框架的Swagger集成库
通过注解自动生成API文档
支持Spring Boot自动配置
提供丰富的自定义选项

1.3.6 Knife4j（增强工具）

功能特性：

基于Swagger UI的增强版本
提供更美观的界面设计
支持接口排序和搜索
增加了离线文档导出功能

Knife4j vs Swagger UI对比：

特性	Swagger UI	Knife4j
界面美观度	一般	优秀
功能丰富度	基础	增强
搜索功能	基础	强大
离线导出	不支持	支持
自定义主题	有限	丰富

1.4 Swagger常用注解详解

在Spring Boot项目中，Swagger通过注解的方式来描述API信息。以下是最常用的注解及其使用方法：

1.4.1 类级别注解

@Api

@Api(tags = "设备管理", description = "设备相关的CRUD操作")
@RestController
@RequestMapping("/api/devices")
public class DeviceController {
    // 控制器实现
}

参数说明：

tags：API分组标签
description：API描述信息
value：API名称（已废弃，建议使用tags）

1.4.2 方法级别注解

@ApiOperation

@ApiOperation(
    value = "创建设备",
    notes = "根据提供的设备信息创建新的物联网设备",
    response = Device.class,
    responseContainer = "Object"
)
@PostMapping
public ResponseEntity<Device> createDevice(@RequestBody Device device) {
    // 方法实现
}

参数说明：

value：操作简要描述
notes：操作详细说明
response：返回值类型
responseContainer：返回值容器类型（List、Set、Map等）

@ApiResponses 和 @ApiResponse

@ApiResponses({
    @ApiResponse(code = 200, message = "操作成功", response = Device.class),
    @ApiResponse(code = 400, message = "请求参数错误"),
    @ApiResponse(code = 401, message = "未授权访问"),
    @ApiResponse(code = 500, message = "服务器内部错误")
})
@GetMapping("/{id}")
public ResponseEntity<Device> getDevice(@PathVariable Long id) {
    // 方法实现
}

1.4.3 参数级别注解

@ApiParam

@GetMapping
public ResponseEntity<List<Device>> getDevices(
    @ApiParam(value = "设备名称", example = "温度传感器")
    @RequestParam(required = false) String name,
    
    @ApiParam(value = "设备状态", allowableValues = "ONLINE,OFFLINE,MAINTENANCE")
    @RequestParam(required = false) String status,
    
    @ApiParam(value = "页码", defaultValue = "1")
    @RequestParam(defaultValue = "1") Integer page
) {
    // 方法实现
}

@ApiImplicitParam 和 @ApiImplicitParams

@ApiImplicitParams({
    @ApiImplicitParam(
        name = "deviceId", 
        value = "设备ID", 
        required = true, 
        dataType = "Long", 
        paramType = "path"
    ),
    @ApiImplicitParam(
        name = "command", 
        value = "控制命令", 
        required = true, 
        dataType = "String", 
        paramType = "body"
    )
})
@PostMapping("/{deviceId}/control")
public ResponseEntity<String> controlDevice(
    @PathVariable Long deviceId,
    @RequestBody String command
) {
    // 方法实现
}

参数类型说明：

path：路径参数
query：查询参数
body：请求体参数
header：请求头参数
form：表单参数

1.4.4 模型级别注解

@ApiModel

@ApiModel(value = "设备信息", description = "物联网设备的基本信息")
public class Device {
    // 属性定义
}

@ApiModelProperty

@ApiModel(value = "设备信息")
public class Device {
    
    @ApiModelProperty(
        value = "设备ID",
        example = "1001",
        required = true,
        position = 1
    )
    private Long id;
    
    @ApiModelProperty(
        value = "设备名称",
        example = "温度传感器-001",
        required = true,
        position = 2
    )
    private String name;
    
    @ApiModelProperty(
        value = "设备状态",
        allowableValues = "ONLINE,OFFLINE,MAINTENANCE",
        example = "ONLINE",
        position = 3
    )
    private String status;
    
    @ApiModelProperty(
        value = "设备位置",
        example = "北京市朝阳区",
        position = 4
    )
    private String location;
    
    @ApiModelProperty(
        value = "创建时间",
        example = "2023-12-01 10:30:00",
        accessMode = ApiModelProperty.AccessMode.READ_ONLY,
        position = 5
    )
    private LocalDateTime createTime;
}

@ApiModelProperty参数说明：

value：属性描述
example：示例值
required：是否必填
allowableValues：允许的值
accessMode：访问模式（READ_ONLY、write_ONLY）
position：显示顺序
hidden：是否隐藏

1.4.5 忽略注解

@ApiIgnore

@RestController
public class InternalController {
    
    @ApiIgnore
    @GetMapping("/internal/health")
    public String healthCheck() {
        return "OK";
    }
}

@JsonIgnore（配合使用）

@ApiModel("用户信息")
public class User {
    
    @ApiModelProperty("用户名")
    private String username;
    
    @JsonIgnore
    @ApiModelProperty(hidden = true)
    private String password;
}

1.4.6 高级注解使用

@ApiParam with complex validation

@PostMapping("/batch")
public ResponseEntity<List<Device>> createDevices(
    @ApiParam(
        value = "设备列表",
        required = true,
        type = "List"
    )
    @RequestBody @Valid List<Device> devices
) {
    // 批量创建设备
}

组合注解使用示例

@Api(tags = "数据采集")
@RestController
@RequestMapping("/api/data")
public class DataController {
    
    @ApiOperation(
        value = "获取设备数据",
        notes = "根据时间范围和设备ID获取传感器数据"
    )
    @ApiImplicitParams({
        @ApiImplicitParam(name = "deviceId", value = "设备ID", required = true, dataType = "Long"),
        @ApiImplicitParam(name = "startTime", value = "开始时间", required = true, dataType = "String"),
        @ApiImplicitParam(name = "endTime", value = "结束时间", required = true, dataType = "String")
    })
    @ApiResponses({
        @ApiResponse(code = 200, message = "查询成功", response = SensorData.class, responseContainer = "List"),
        @ApiResponse(code = 400, message = "参数错误"),
        @ApiResponse(code = 404, message = "设备不存在")
    })
    @GetMapping("/sensor/{deviceId}")
    public ResponseEntity<List<SensorData>> getSensorData(
        @PathVariable Long deviceId,
        @RequestParam String startTime,
        @RequestParam String endTime
    ) {
        // 实现逻辑
    }
}

1.5 注解使用最佳实践

保持一致性：在整个项目中使用统一的注解风格
提供示例值：使用example属性提供有意义的示例
详细描述：为复杂的API提供详细的notes说明
合理分组：使用tags对API进行逻辑分组
响应码完整：为所有可能的响应码提供说明
参数验证：结合Bean Validation注解进行参数校验
版本管理：通过不同的Controller或路径管理API版本

二、市面上主流API工具对比分析

在API文档和测试领域，除了Swagger生态系统外，还有许多优秀的工具。了解这些工具的关系、区别和发展历程，有助于我们做出更好的技术选型。

2.1 工具关系图谱

API文档生态系统
├── 规范标准
│   ├── OpenAPI 3.0 (原Swagger规范)
│   ├── API Blueprint
│   └── RAML
├── 文档生成工具
│   ├── Swagger生态
│   │   ├── Swagger UI (官方)
│   │   ├── Swagger Editor
│   │   ├── Swagger Codegen
│   │   └── SpringFox (Java集成)
│   ├── 增强工具
│   │   ├── Knife4j (国产增强)
│   │   ├── ReDoc
│   │   └── Swagger Bootstrap UI
│   └── 独立平台
│       ├── Apifox (国产一体化)
│       ├── Postman
│       ├── Insomnia
│       └── YApi
└── 企业级解决方案
    ├── Kong Developer Portal
    ├── AWS API Gateway
    └── Azure API Management

2.2 核心工具详细对比

Swagger vs SpringFox vs Knife4j vs Apifox

特性维度	Swagger UI	SpringFox	Knife4j	Apifox
定位	官方UI展示工具	Java集成框架	增强UI工具	一体化API平台
发布时间	2011年	2015年	2019年	2021年
主要功能	文档展示、在线测试	注解生成文档	美化UI、增强功能	设计、文档、测试、Mock
技术栈	JavaScript/HTML	Java/Spring	Vue.js/Java	Electron/Web
部署方式	嵌入式/独立部署	嵌入Spring应用	嵌入Spring应用	桌面应用/云服务
界面美观度	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
功能丰富度	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
学习成本	低	中	低	中
社区活跃度	极高	高	中	中
企业采用度	极高	高	中	快速增长
文档导出	不支持	不支持	支持	支持
Mock服务	不支持	不支持	不支持	支持
团队协作	不支持	不支持	基础支持	强大支持
版本管理	不支持	不支持	不支持	支持
自动化测试	基础	基础	基础	强大

2.3 各工具详细分析

1. Swagger UI（官方工具）

// 基础配置示例
SwaggerUIBundle({
  url: 'https://api.example.com/swagger.json',
  dom_id: '#swagger-ui',
  deepLinking: true,
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUIBundle.plugins.DownloadUrl
  ],
  layout: "StandaloneLayout"
});

优势：

官方维护，稳定性最高
社区支持最完善
与OpenAPI规范完全兼容
插件生态丰富

劣势：

界面相对简陋
功能相对基础
缺少高级特性

2. SpringFox（Java生态集成）

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("基于SpringFox生成的API文档")
                .version("1.0.0")
                .build();
    }
}

优势：

与Spring生态深度集成
注解驱动，开发友好
自动扫描生成文档
支持多种认证方式

劣势：

仅限Java/Spring项目
更新频率较慢
对OpenAPI 3.0支持有限

3. Knife4j（国产增强工具）

@Configuration
@EnableKnife4j
@EnableSwagger2
public class Knife4jConfig {
    
    @Bean
    public Docket defaultApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("默认分组")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }
}

特色功能：

离线文档导出：支持导出HTML、Word、PDF格式
接口排序：支持自定义接口显示顺序
搜索增强：全局搜索接口和参数
主题定制：多种UI主题可选
调试增强：更好的参数输入体验

优势：

界面美观，用户体验好
功能丰富，开箱即用
中文文档完善
持续更新维护

劣势：

社区相对较小
主要面向中文用户
依赖SpringFox基础

4. Apifox（一体化API平台）

{
  "name": "用户管理API",
  "description": "用户相关的CRUD操作",
  "method": "POST",
  "url": "/api/users",
  "headers": [
    {
      "name": "Content-Type",
      "value": "application/json"
    }
  ],
  "body": {
    "type": "json",
    "raw": {
      "username": "@string",
      "email": "@email",
      "age": "@integer(18,65)"
    }
  },
  "response": {
    "status": 200,
    "body": {
      "code": 0,
      "message": "success",
      "data": {
        "id": "@integer",
        "username": "@string",
        "email": "@email"
      }
    }
  }
}

核心特性：

API设计优先：可视化API设计器
智能Mock：基于数据模型自动生成Mock数据
自动化测试：支持接口自动化测试
团队协作：多人协作、权限管理
版本控制：API版本管理和变更追踪
代码生成：多语言SDK自动生成

优势：

功能最全面，一站式解决方案
用户体验优秀
支持API全生命周期管理
强大的团队协作功能

劣势：

相对较新，生态还在建设中
企业版收费
学习成本相对较高

2.4 文档导出功能发展历程

时间线分析：

2011-2015年：基础阶段

Swagger UI只提供在线查看功能
主要解决API文档展示问题
无导出功能，依赖浏览器打印

2016-2018年：需求萌芽

企业开始重视API文档的离线分享
社区出现第三方导出插件
主要通过浏览器插件或脚本实现

2019年：Knife4j引领

Knife4j 2.0首次内置文档导出功能
支持导出HTML、Word格式
成为国内首个支持离线导出的Swagger增强工具

// Knife4j导出配置示例
@Configuration
public class Knife4jConfig {
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true) // 启用文档导出
                .apiInfo(new ApiInfoBuilder()
                    .title("API文档")
                    .description("支持离线导出的API文档")
                    .version("1.0")
                    .build())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

2020-2021年：功能完善

Knife4j 3.0增加PDF导出支持
导出格式更加丰富和美观
支持自定义导出模板

2021年至今：平台化发展

Apifox等新一代工具原生支持多格式导出
不仅支持文档导出，还支持测试用例导出
云端协作，支持在线分享和版本管理

导出功能对比：

工具	HTML导出	Word导出	PDF导出	自定义模板	批量导出	云端分享
Swagger UI	❌	❌	❌	❌	❌	❌
SpringFox	❌	❌	❌	❌	❌	❌
Knife4j	✅	✅	✅	✅	✅	❌
Apifox	✅	✅	✅	✅	✅	✅
Postman	✅	❌	✅	✅	✅	✅
YApi	✅	❌	❌	❌	✅	✅

2.5 选型建议

根据项目需求选择：

1. 传统Java项目

推荐：SpringFox + Knife4j
理由：
- 与Spring生态完美集成
- 注解驱动，开发效率高
- Knife4j提供美观界面和导出功能
- 成本低，学习曲线平缓

2. 微服务架构

推荐：Swagger UI + 网关聚合
理由：
- 标准化程度高
- 便于服务间文档聚合
- 社区支持最好
- 长期维护有保障

3. 团队协作重点

推荐：Apifox
理由：
- 一体化解决方案
- 强大的团队协作功能
- 支持API全生命周期管理
- 现代化的用户体验

4. 企业级应用

推荐：Apifox企业版 或 自建Swagger + 定制开发
理由：
- 安全性和可控性更高
- 支持私有化部署
- 可定制化程度高
- 符合企业治理要求

2.6 未来发展趋势

1. 标准化趋势

OpenAPI 3.1规范进一步完善
更好的JSON Schema支持
异步API规范的兴起

2. 智能化发展

AI辅助API设计
智能测试用例生成
自动化文档维护

3. 云原生集成

与DevOps流程深度集成
容器化部署标准化
服务网格集成

4. 协作平台化

更强的团队协作功能
版本控制和变更管理
跨团队API治理

通过了解这些工具的发展历程和特点，我们可以根据项目的具体需求和团队情况，选择最适合的API文档解决方案。在物联网平台这样的复杂系统中，建议采用SpringFox + Knife4j的组合，既能满足开发效率要求，又能提供良好的文档体验和导出功能。

三、Swagger技术栈选型与依赖配置

3.1 技术栈选择

在物联网平台项目中，我们选择了以下Swagger技术栈：

Swagger2 (SpringFox): 2.9.2版本，作为核心文档生成引擎
Knife4j: 2.0.9版本，提供增强的UI界面和更好的用户体验
Swagger Bootstrap UI: 1.9.4版本，作为备选UI方案

3.2 Maven依赖配置

<!-- Swagger2核心组件 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!-- Swagger UI界面 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- 修复2.9.2版本NumberFormatException的依赖 -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.6.0</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.6.0</version>
</dependency>

<!-- Knife4j增强UI组件 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

依赖配置要点说明：

版本兼容性处理：通过exclusions排除冲突的依赖，手动指定兼容版本
UI增强：Knife4j提供了比原生Swagger UI更好的界面体验
问题修复：特定版本的swagger-models解决了NumberFormatException问题

四、核心配置类设计

4.1 主配置类架构

@EnableKnife4j
@EnableSwagger2
@Profile({"dev"})
@Configuration
public class SwaggerConfig implements WebMvcConfigurer {
    
    @Autowired
    private SwaggerBasicConfig swaggerBasicConfig;
    
    /**
     * 静态资源处理
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
    
    // 其他配置方法...
}

配置类设计亮点：

环境隔离：使用@Profile({"dev"})确保只在开发环境启用
UI增强：同时启用Knife4j和原生Swagger UI
资源映射：完整的静态资源路径配置

4.2 模块化API分组策略

在物联网平台中，我们按照业务模块对API进行分组管理：

/**
 * 系统管理模块API
 */
@Bean
public Docket systemApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("1. 系统管理")
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.company.iot.admin.controller.system"))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(securitySchemes())
            .securityContexts(securityContexts());
}

/**
 * 设备管理模块API
 */
@Bean
public Docket deviceApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("2. 设备管理")
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.company.iot.admin.controller.device"))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(securitySchemes())
            .securityContexts(securityContexts());
}

/**
 * 数据处理模块API
 */
@Bean
public Docket dataApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("3. 数据处理")
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.company.iot.admin.controller.data"))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(securitySchemes())
            .securityContexts(securityContexts());
}

分组策略优势：

清晰的模块划分：按照业务领域进行API分组
便于团队协作：不同团队可以专注于各自负责的模块
降低文档复杂度：避免单一文档过于庞大
统一安全配置：所有分组共享相同的安全策略

4.3 API信息配置

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("物联网平台 API 文档")
            .description("基于 Spring Boot 的物联网平台，提供设备管理、数据采集、实时监控等功能")
            .contact(new Contact("开发团队", "http://localhost:8900/doc.html", "team@company.com"))
            .termsOfServiceUrl("http://localhost:8900/doc.html")
            .version("1.0")
            .build();
}

总结

在实际应用中，建议根据项目规模和团队需求选择合适的工具组合。对于大多数Java项目，SpringFox + Knife4j的组合能够提供良好的开发体验和文档质量。

参考：https://developer.aliyun.com/article/1157293 https://blog.csdn.net/zhanggonglalala/article/details/98070986 https://doc.xiaominfo.com/v2/documentation/knife4j-front-execute.html

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

腾讯技术创作特训营S15#自选日志