Swagger3介绍
开发中有很多接口的开发，接口需要配合完整的接口文档才更方便沟通、使用，Swagger是一个用于自动生成在线接口文档的框架，并可在线测试接口，可以很好的跟Spring结合，只需要添加少量的代码和注解即可，而且在接口变动的同时，即可同步修改接口文档，不用再手动维护接口文档。Swagger3是17年推出的最新版本，相比于Swagger2配置更少，使用更方便
开发环境
JDK 11
SpringBoot 2.5.4
添加Maven依赖
<!--swagger3-->\n<dependency>\n <groupId>io.springfox</groupId>\n <artifactId>springfox-boot-starter</artifactId>\n <version>3.0.0</version>\n</dependency> 添加Swagger配置类
package com.springboot.admin.Swagger;\n\nimport io.swagger.annotations.ApiOperation;\nimport org.springframework.context.annotation.Bean;\nimport org.springframework.context.annotation.Configuration;\nimport springfox.documentation.builders.ApiInfoBuilder;\nimport springfox.documentation.builders.PathSelectors;\nimport springfox.documentation.builders.RequestHandlerSelectors;\nimport springfox.documentation.oas.annotations.EnableOpenApi;\nimport springfox.documentation.service.ApiInfo;\nimport springfox.documentation.spi.DocumentationType;\nimport springfox.documentation.spring.web.plugins.Docket;\n\n@EnableOpenApi\n@Configuration\npublic class SwaggerConfig {\n @Bean\n public Docket createRestApi() {\n return new Docket(DocumentationType.OAS_30)\n .apiInfo(apiInfo())\n .select()\n //设置通过什么方式定位需要自动生成文档的接口，这里定位方法上的@ApiOperation注解\n .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))\n //接口URI路径设置，any是全路径，也可以通过PathSelectors.regex()正则匹配\n .paths(PathSelectors.any())\n .build();\n }\n private ApiInfo apiInfo() {\n return new ApiInfoBuilder()\n .title("Swagger3接口文档")\n .version("1.0")\n .description("API 描述")\n .build();\n\n }\n}\n 使用Swagger
- 在接口类上添加@Api(tags = "操作接口")，tags的值是该类的作用，在文档页面会显示，value不会显示
- 在需要生成文档的接口上添加注解@ApiOperation
- 对请求参数添加@ApiParam
示例如下
package com.springboot.admin.controller;\n\nimport com.springboot.admin.jwt.JwtAuthService;\nimport io.swagger.annotations.Api;\nimport io.swagger.annotations.ApiImplicitParam;\nimport io.swagger.annotations.ApiImplicitParams;\nimport io.swagger.annotations.ApiOperation;\nimport org.springframework.beans.factory.annotation.Autowired;\nimport org.springframework.boot.system.ApplicationHome;\nimport org.springframework.security.access.annotation.Secured;\nimport org.springframework.security.access.prepost.PreAuthorize;\nimport org.springframework.web.bind.annotation.GetMapping;\n\nimport org.springframework.web.bind.annotation.RestController;\n\n\n\n@RestController\n@Api(tags = "测试接口")\npublic class TestController {\n @Autowired\n JwtAuthService jwtAuthService;\n\n @GetMapping("/test")\n @ApiOperation(value="测试接口1", notes="获取当前目录")\n @ApiImplicitParams({\n @ApiImplicitParam(name = "name", value = "名字", dataType = "String", required = true),\n @ApiImplicitParam(name = "typeId", value = "类型ID", dataType = "Long", required = true)\n })\n public String test() throws Exception {\n\n // 获取当前目录\n ApplicationHome ah = new ApplicationHome(JwtAuthService.class);\n String docStorePath = ah.getSource().getParentFile().toString();\n System.out.println(docStorePath);\n\n return "hello world";\n }\n\n @GetMapping("/a")\n @Secured("ROLE_abc")\n @ApiOperation(value="测试接口2", notes="测试权限接口")\n public String a() {\n return "hello a api";\n }\n\n @GetMapping("/b")\n @PreAuthorize("hasRole('abcc')")\n @ApiOperation(value = "测试接口3",notes="测试权限接口333")\n public String b() {\n return "hello b api";\n }\n}\n 查看效果：
启动服务后，就可以查看在线文档了，本地服务的地址是http://localhost:8080/swagger-ui/index.html，还可以通过Try it out 来测试。
如果应用有带上下文，那么地址地址也要加上上下文，比如：http://localhost:8091/bootService/swagger-ui/index.html
注意：
如果应用有引入security，那么需要将swagger相关资源放行：
// 放行swagger3相关资源\n\n.antMatchers("/swagger-ui/**").permitAll()\n.antMatchers("/webjars/**").permitAll()\n.antMatchers("/v3/**").permitAll()\n.antMatchers("/swagger-resources/**").permitAll()