前后端分离项目必备——自动生成API文档神器Swagger

Swagger的故事

随着Web服务的发展，RESTful风格的API越来越受到开发者的青睐，因为它简单且符合Web的本质。Spring框架也不落人后，提供了一个名为Spring MVC的模块，用于支持RESTful API的开发。Spring MVC是一个基于注解的Web框架，让开发者可以使用简洁且优雅的方式定义和实现API。

然而Spring MVC并没有提供一个方便且标准的方式来描述和文档化API，这给API的管理和维护带来了一定的困难。为了解决这个问题，一个名为Swagger的项目诞生了。Swagger是由Tony Tam在2010年创建的一个开源项目，旨在为RESTful API提供一个规范且完整的框架4。Tony Tam是一个资深的Java开发者，他在使用Spring MVC开发API时感受到了它的优点和缺点，所以他决定创建一个可以与Spring MVC无缝集成的工具，来帮助开发者更好地设计、描述、调用和可视化API。

Swagger项目很快就得到了开源社区和业界的认可和支持，成为了最流行的API开发工具之一。Swagger项目也不断地演进和完善，涵盖了各种语言和框架，如Python, Ruby, Node.js, Django, Rails等。Swagger项目也不断地与其他标准和工具集成，如OpenAPI Specification, Postman, Apigee等。

Swagger的作用

Swagger的主要作用是为RESTful风格的Web服务提供一个标准且完整的框架，包括以下几个方面：

• 生成：Swagger可以根据代码或者手动编写的规范文件，自动生成API文档，包括请求参数、响应结果、错误码等信息。这样可以节省编写文档的时间，也可以保证文档和代码的一致性。
• 描述：Swagger可以使用一种结构化的语言（如YAML或JSON）来描述API的元数据，如接口名称、路径、方法、参数类型、返回值类型等。这样可以方便地对API进行管理和维护，也可以方便地进行版本控制和协作开发。
• 调用：Swagger可以提供一个可视化的用户界面（如Swagger UI），让用户可以直接在浏览器中对API进行测试和调试，而不需要使用其他的工具（如Postman或curl）。这样可以提高开发效率，也可以方便地验证API的功能和性能。
• 可视化：Swagger可以提供一个图形化的用户界面（如Swagger Editor），让用户可以以图形化的方式编辑和查看API规范文件，而不需要关心语法细节。这样可以提高用户体验，也可以方便地进行错误检查和修正。

Swagger的好处

Swagger作为一个流行且成熟的API开发工具，它有以下几个好处：

• 标准化：Swagger遵循OpenAPI规范，这是一个业界公认且广泛使用的RESTful API描述标准。使用Swagger可以保证API的兼容性和互操作性，也可以方便地与其他遵循OpenAPI规范的工具集成。
• 灵活性：Swagger支持多种编程语言和框架，如Java, Python, Ruby, Node.js, Spring, Django, Rails等。使用Swagger可以根据不同的需求和场景选择合适的技术栈，也可以轻松地迁移和重构代码。
• 易用性：Swagger提供了丰富且易用的工具和用户界面，让用户可以快速地创建、修改、查看和测试API。使用Swagger可以降低API开发的门槛和难度，也可以提高API开发的质量和效率。

Swagger项目现在已经成为了一个庞大且活跃的生态系统，包括以下几个部分：

• Swagger Core：提供了一系列的库和工具，用于生成、解析、验证和转换Swagger规范文件。
• Swagger UI：提供了一个可视化的用户界面，用于展示、测试和调试API。
• Swagger Editor：提供了一个图形化的用户界面，用于编辑和查看Swagger规范文件。
• Swagger Codegen：提供了一个代码生成器，用于根据Swagger规范文件生成客户端和服务端代码。
• Swagger Inspector：提供了一个在线工具，用于检查、测试和分析API。
• Swagger Hub：提供了一个在线平台，用于协作、管理和发布API。

Springboot使用Swagger3生成API文档

步骤说明

• 在pom.xml文件中添加springdoc-openapi-ui依赖，这是一个支持OAS 3.0的Swagger UI库，它可以自动集成到Spring Boot应用中，并提供一个可视化的用户界面来展示、测试和调试API。
• 在配置类中添加@OpenAPIDefinition注解，并定义一些API的基本信息，如标题、描述、版本、联系人等。
• 在控制器类中添加@Tag注解，并定义一些API的分组信息，如名称、描述等。
• 在方法上添加@Operation注解，并定义一些API的操作信息，如摘要、描述、响应等。
• 在参数上添加@Parameter注解，并定义一些API的参数信息，如名称、描述、是否必填、示例等。
• 在模型类上添加@Schema注解，并定义一些API的模型信息，如名称、描述、属性等。

注意：

对于2.x.x版本，访问地址为：http://localhost:8080/{context-path}/swagger-ui.html

对于3.x.x版本，访问地址为：http://localhost:8080/{context-path}/swagger-ui/index.html

其中，localhost是你的本地主机名，8080是你的项目端口号，{context-path}是你的项目上下文路径。你需要根据你的实际情况来替换这些参数。

例如，如果你的项目端口号是8081，上下文路径是demo，Swagger版本是3.0.0，那么你可以访问以下地址来查看Swagger UI界面：

http://localhost:8081/demo/swagger-ui/index.html

pom.xml文件

    
    
        org.springframework.boot
        spring-boot-starter-web
    
    
    
        org.springdoc
        springdoc-openapi-ui
        1.5.12
    

配置类

// 配置类
@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "Swagger3示例API",
                description = "这是一个使用Swagger3来开发Spring Boot应用中的API的示例",
                version = "1.0",
                contact = @Contact(
                        name = "张三",
                        email = "zhangsan@example.com",
                        url = "1"
                )
        )
)
public class SwaggerConfig {
}

控制器类

// 控制器类
@RestController
@RequestMapping("/user")
@Tag(name = "用户管理API", description = "提供用户相关的操作")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "根据ID查询用户信息", description = "返回用户实体对象")
    @ApiResponse(responseCode = "200", description = "查询成功")
    @ApiResponse(responseCode = "404", description = "用户不存在")
    public User getUserById(@PathVariable("id") @Parameter(description = "用户ID", required = true, example = "1") Long id) {
        // 模拟查询数据库
        User user = new User();
        user.setId(id);
        user.setName("张三");
        user.setAge(18);
        return user;
    }

    @PostMapping("/")
    @Operation(summary = "添加用户信息", description = "返回添加结果")
    @ApiResponse(responseCode = "200", description = "添加成功")
    @ApiResponse(responseCode = "400", description = "参数错误")
    public String addUser(@RequestBody @Parameter(description = "用户实体对象", required = true) User user) {
        // 模拟插入数据库
        return "添加成功";
    }

}

用户实体类

// 用户实体类
@Schema(name = "用户实体类", description = "用户的基本信息")
public class User {

    @Schema(description = "用户ID")
    private Long id;

    @Schema(description = "用户姓名")
    private String name;

    @Schema(description = "用户年龄")
    private Integer age;

    // 省略getter和setter方法
}

Swagger注解总结：

Swagger注解有以下几种类型：

• 类级别的注解：用于标识一个类是Swagger的资源，可以设置一些全局的属性，如tags、value等。常用的类级别的注解有@Api。
• 方法级别的注解：用于标识一个方法是一个http请求的操作，可以设置一些操作相关的属性，如value、notes、response等。常用的方法级别的注解有@ApiOperation、@ApiResponses、@ApiResponse等。
• 参数级别的注解：用于标识一个方法的参数或者一个字段是API的参数，可以设置一些参数相关的属性，如value、required、example等。常用的参数级别的注解有@ApiParam、@ApiImplicitParam等。
• 模型级别的注解：用于标识一个类是API的模型，可以设置一些模型相关的属性，如value、description等。常用的模型级别的注解有@ApiModel、@ApiModelProperty等。
• 忽略级别的注解：用于标识一个类或者方法被忽略，不显示在Swagger文档上。常用的忽略级别的注解有@ApiIgnore。

下面是一个对Swagger常用注解的总结表格：