在SpringBoot中使用Swagger2构建API文档

作者: liushiping | 来源:发表于2023-06-12 16:23 被阅读0次

一、API接口文档的重要性

目前很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维护一份及时更新且完整的API 文档将会大大的提高我们的工作效率。传统意义上的文档都是后端开发人员使用word编写的，这种方式很难保证文档的及时性，久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式，既可以根据代码自动生成 API 文档，也可以通过Swagger UI 直接在文档页面尝试 API 的调用，很好的保证了文档的时效性及开发调试效率。

二、在项目中整合swagger2

2.1通过Maven引入相关类库

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

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

2.2通过java Config对Swagger2进行配置

@Profile({"dev","test"})
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger文档案例")
                .description("用于演示swagger API文档案例")
                .version("1.0")
                .build();
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())
                        .select()
                        //扫描basePackage包下面的“/demo/”路径下的内容作为接口文档构建的目标
                        .apis(RequestHandlerSelectors.basePackage("cn.lsp.springboot"))
                        .paths(PathSelectors.regex("/demo/.*"))
                        .build();
    }
}

@EnableSwagger2 注解表示开启SwaggerAPI文档相关的功能；
ApiInfo类用于配置接口文档的title(标题)、描述、termsOfServiceUrl（服务协议）、版本等相关信息；
basePackage表示扫描哪个package下面的Controller类作为API接口文档内容范围；
paths表示哪一个请求路径下控制器映射方法，作为API接口文档内容范围；

2.3在application.yml中增加配置

如果在配置完swagger后，启动项目过程中报错：Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException，则配置一下内容：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

原因：这是因为Springfox使用的路径匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher。
解决：在application.properties里配置：spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER。

2.4swagger的使用

集成完成之后，启动项目并访问：http://localhost:8080/swagger-ui.html ，如下：

swagger
swagger将自动扫描2.2节配置的RequestHandlerSelectors.basePackage("cn.lsp.springboot")包下、PathSelectors.regex("/demo/.*")路径下所有Controller，收集端点信息自动生成swagger文档。

三、使用swagger注解

我们还可以对swagger自动生成的API文档内容进行修改，使得API文档更具可读性。这就需要在Controller接口上增加Swagger注解来实现。

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
 
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
 
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
 
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性
@ApiIgnore()用于类，方法，方法参数 表示这个方法或者类被忽略

@Api(value = "question open Api Client", description = "试题开放 API", protocols = "application/json")
@RequestMapping("/open-api")
public interface QuestionOpenApi {

    @ApiOperation(value = "获取所有学段", notes = "获取所有学段", nickname = "periods")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "access-key", value = "access-key", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "access-token", value = "access-token", dataType = "string", paramType = "header", required = true)
    })
    @RequestMapping(value = "/periods", method = RequestMethod.GET)
    List<OpenPeriodDTO> periods();

    @ApiOperation(value = "获取所有学科", notes = "获取所有学科", nickname = "subjects")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "access-key", value = "access-key", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "access-token", value = "access-token", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "periodId", value = "学段id", paramType = "path", dataType = "string", required = true)
    })
    @RequestMapping(value = "/subjects/{periodId}", method = RequestMethod.GET)
    List<OpenSubjectDTO> subjects(@PathVariable("periodId") String periodId);

    @ApiOperation(value = "获取某科目学科题型", notes = "获取某科目学科题型", nickname = "subjectTypes")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "access-key", value = "access-key", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "access-token", value = "access-token", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "periodId", value = "学段id", paramType = "query", dataType = "string", required = true),
            @ApiImplicitParam(name = "subjectId", value = "学科id", paramType = "query", dataType = "string", required = true)
    })
    @RequestMapping(value = "/subject-types", method = RequestMethod.GET)
    List<OpenSubjectTypeDTO> subjectTypes(@RequestParam("periodId") String periodId, @RequestParam("subjectId") String subjectId);

    @ApiOperation(value = "获取某科目知识点", notes = "获取某科目知识点", nickname = "points")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "access-key", value = "access-key", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "access-token", value = "access-token", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "periodId", value = "学段id", paramType = "query", dataType = "string", required = true),
            @ApiImplicitParam(name = "subjectId", value = "学科id", paramType = "query", dataType = "string", required = true)
    })
    @RequestMapping(value = "/points", method = RequestMethod.GET)
    KnowledgePointTreeListDTO points(@RequestParam("periodId") String periodId, @RequestParam("subjectId") String subjectId);

    @ApiOperation(value = "搜索试题", notes = "搜索试题", nickname = "search")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "access-key", value = "access-key", dataType = "string", paramType = "header", required = true),
            @ApiImplicitParam(name = "access-token", value = "access-token", dataType = "string", paramType = "header", required = true),
        @ApiImplicitParam(name = "param", value = "参数", paramType = "body", dataType = "ParamQuestionDTO", required = true)
    })
    @RequestMapping(value = "/questions", method = RequestMethod.GET)
    PageableData<QuestionDTO> questions(@RequestBody @Valid ParamQuestionDTO param);
}

预览图如下：

Swagger API文档预览图

四、生产环境下禁用swagger

我们的文档通常是在团队内部观看及使用的，不希望发布到生产环境让用户看到。

禁用方法1：使用注解@Profile({"dev","test"}) 表示在开发或测试环境开启，而在生产关闭。
禁用方法2：使用注解@ConditionalOnProperty(name = "swagger.enable", havingValue = "true") 然后在测试配置或者开发配置中添加 swagger.enable = true 即可开启，生产环境不填则默认关闭Swagger.

五、Swagger3及OpenAPI规范

OpenAPI是规范的正式名称。规范的开发工作于2015年启动，当时SmartBear（负责Swagger工具开发的公司）将Swagger 2.0规范捐赠给了Open API Initiative，该协会由来自技术领域不同领域的30多个组织组成。此后，该规范被重命名为OpenAPI规范。
Swagger
- 是一个 API文档维护组织，后来成为了 Open API 标准的主要定义者。现在最新的版本为17年发布的 Swagger3（Open Api3）。
- 是一个Open API规范实现工具包，由于Swagger工具是由参与创建原始Swagger规范的团队开发的，因此通常仍将这些工具视为该规范的代名词。目前可以认为Swagger3就是Open API 3.0
OpenAPI 3.0：2017年7月，Open API Initiative最终发布了OpenAPI Specification 3.0.0。它对2.0规范进行了很多改进。Open API 3.0规范可以用JSON或YAML编写，并且在记录RESTful API方面做得很好。同时标志着Swagger2成为过去式。
SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。截至2020年4月，尚未支持 OpenAPI3 标准。
SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中。
也是用来在 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用

要使用OpenAPI（swagger3），只需在项目的pom.xml中添加如下OpenAPI依赖即可：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.4.0</version>
</dependency>

在SpringBoot中使用Swagger2构建API文档

一、API接口文档的重要性

二、在项目中整合swagger2

2.1通过Maven引入相关类库

2.2通过java Config对Swagger2进行配置

2.3在application.yml中增加配置

2.4swagger的使用

三、使用swagger注解

四、生产环境下禁用swagger

五、Swagger3及OpenAPI规范

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读