代码即文档之Swagger

背景

在程序员所撰写的文档中，接口文档起着至关重要的作用。然而，许多接口涉及大量的输入和输出字段，而且这些信息已经在代码中有所体现。那么，为何还要重复书写这些内容呢？此时，我们可以考虑采用Swagger，让代码直接生成可用的接口文档，从而简化流程。

介绍

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，可以支持接口文档的生成和接口测试。由服务器端的代码直接生成接口文档中的内容，允许API来始终保持同步。

官方文档：https://swagger.io/docs/specification/2-0/basic-structure/

准备

环境

• Java
• Spring
• Gradle
• Swagger2

引入依赖

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

使用示例

1. 配置Swagger

下面是一个最基本的配置，定义了API所在的包目录为"com.example.demo"，以及Swagger文档的标题为”demo“

@Configuration
public class Swagger2Config {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build()
                .apiInfo(new ApiInfoBuilder().title("demo").build());
    }
}

2. 启用Swagger

在启动类上使用注解@EnableSwagger2，这样启动时就会启用swagger

@SpringBootApplication
@EnableSwagger2
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

}

3. 添加接口

@RestController
public class TestController {
    @ApiOperation(value = "测试输出特定字符串")
    @GetMapping("test")
    public String test() {
        return "hello world";
    }

    @ApiOperation(value = "测试输出body中的字符串")
    @PostMapping("test")
    public String testPrint(@RequestBody String input) {
        return input;
    }
}

在每个接口上使用@ApiOperation就可以定义该接口的标题，在生成Swagger文档后该名称就会显示。

4. 启动程序并查看Swagger文档

我的程序运行在8080接口，所以当程序运行后，我进入http://localhost:8080/swagger-ui.html 就可以看到生成的Swagger文档。

5. 使用Swagger调用接口以进行测试

在我这个示例中，有一个POST接口会根据RequestBody中的字符串进行输出。我们就用这个接口做一下测试，点击展开该接口后点击【Try it out】button就可以进行测试。

输入RequestBody中的值后，就可以点击【Execute】使用该input做测试。

当我输入“string”后就可以看到返回结果，Code=200表示接口成功调用，Response Body中成功输出了“string”结果。

优点

• 对于后端开发人员来说，只要写好代码就可以生成对应的文档，不需要再另外耗费时间去维护文档。同时当代码有所改动后，文档也会进行相应的修改，再也不用担心文档和代码不一致的问题了。
• 对于前端开发来说，查看接口文档也更加方便，只要后端把代码写好就可以同步看到。同时前端开发也可以直接使用Swagger进行接口调用和测试。
• 对于测试人员来说，也可以直接使用Swagger进行测试，不需要理解代码也不需要去学习使用Postman等工具。
• 对于团队管理人员来说，技术文档可以实时反应目前服务器中的代码状态，也不用再去催促技术人员将文档更新为最新版本，减少了管理成本。