当前位置: 首页>后端>正文

在SpringBoot中使用Swagger2构建API文档

一、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 ,如下:

在SpringBoot中使用Swagger2构建API文档,第1张
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);
}
预览图如下:
在SpringBoot中使用Swagger2构建API文档,第2张
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>

https://www.xamrdz.com/backend/3za1936733.html

相关文章: