一、导入依赖
<!-- Swagger的注解依赖包 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0</version> </dependency> <!-- Swagger接口文档页面包 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>3.0.0</version> </dependency>
二、配置类
package com.example.swagger2.config; import io.swagger.annotations.ApiOperation; import io.swagger.models.auth.In; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.*; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spi.service.contexts.SecurityContext; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.ArrayList; import java.util.List; /** * @author feimao * @date 2022-03-30 */ @Configuration @EnableSwagger2 public class Swagger2Config extends WebMvcConfigurationSupport { /** * 创建API */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // 是否启用Swagger（可写到配置文件application.yml中） .enable(true) // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息） .apiInfo(apiInfo()) // 设置哪些接口暴露给Swagger展示 .select() // 扫描所有有注解的api，用这种方式更灵活 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) // 扫描指定包中的swagger注解 // .apis(RequestHandlerSelectors.basePackage("com.example.swagger2")) // 扫描所有 .apis(RequestHandlerSelectors.any()) //为任何接口生成API文档 .paths(PathSelectors.any()) .build() /* 设置安全模式，swagger可以设置访问token */ //.securitySchemes(securitySchemes()) //.securityContexts(securityContexts()) // 统一请求前缀（可写到配置文件application.yml中） .pathMapping("/dev-api"); } /** * 安全模式，这里指定token通过Authorization头请求头传递 */ //private List<SecurityScheme> securitySchemes() { // List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>(); // apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue())); // return apiKeyList; //} /** * 安全上下文 */ //private List<SecurityContext> securityContexts() { // List<SecurityContext> securityContexts = new ArrayList<>(); // securityContexts.add( // SecurityContext.builder() // .securityReferences(defaultAuth()) // .operationSelector(o -> o.requestMappingPattern().matches("/.*")) // .build()); // return securityContexts; //} /** * 默认的安全上引用 */ //private List<SecurityReference> defaultAuth() { // AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); // AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; // authorizationScopes[0] = authorizationScope; // List<SecurityReference> securityReferences = new ArrayList<>(); // securityReferences.add(new SecurityReference("Authorization", authorizationScopes)); // return securityReferences; //} /** * 配置swagger2的静态资源路径 * * @param registry */ @Override protected void addResourceHandlers(ResourceHandlerRegistry registry) { // 解决静态资源无法访问 registry.addResourceHandler("/**") .addResourceLocations("classpath:/static/"); // 解决swagger无法访问 registry.addResourceHandler("/swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); // 解决swagger的js文件无法访问 registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } /** * 添加摘要信息 */ private ApiInfo apiInfo() { // 用ApiInfoBuilder进行定制 return new ApiInfoBuilder() // 设置标题 .title("标题：xx管理系统_接口文档") // 描述 .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...") // 作者信息 .contact(new Contact("feimao", "http://项目地址、公司官网.com", "123@163.com")) // 版本 .version("版本号:1.0") .build(); } /** * 创建一个分组（可选，创建分组后会在界面右上角切换） * @return */ @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .groupName("肥猫的分组") // 配置分组详情 .apiInfo(apiInfo()); } }
三、Swagger2注解详解
1、@Api ：请求类的说明
@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。 tags="说明该类的作用" value="该参数没什么意义，所以不需要配置"
举例：
@Api(tags = "账户相关模块") @RestController @RequestMapping("/api/account") public class AccountController { //TODO }
3、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明
@ApiImplicitParams：用在请求的方法上，包含一组参数说明 @ApiImplicitParam：对单个参数的说明 name：参数名 value：参数的汉字说明、解释 required：参数是否必须传 paramType：参数放在哪个地方 · header --> 请求参数的获取：@RequestHeader · query --> 请求参数的获取：@RequestParam · path（用于restful接口）--> 请求参数的获取：@PathVariable · body（请求体）--> @RequestBody User user · form（普通表单提交） dataType：参数类型，默认String，其它值dataType="int" defaultValue：参数的默认值
举例：
@ApiOperation(value="用户登录",notes="随边说点啥") @ApiImplicitParams({ @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"), @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"), @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer") }) @PostMapping("/login") public AjaxResult login(@RequestParam String mobile, @RequestParam String password, @RequestParam Integer age){ //TODO return AjaxResult.OK(); }
单个参数举例
@ApiOperation("根据部门Id删除") @ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query") @GetMapping("/delete") public AjaxResult delete(String depId) { //TODO }
4、@ApiResponses、@ApiResponse：方法返回值的说明
@ApiResponses：方法返回对象的说明 @ApiResponse：每个参数的说明 code：数字，例如400 message：信息，例如"请求参数没填好" response：抛出异常的类
举例：
@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里") @ApiResponses({ @ApiResponse(code = 400, message = "请求参数没填好"), @ApiResponse(code = 404, message = "请求路径找不到") }) @PostMapping("/changepass") public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo, @RequestBody @Valid PasswordModel passwordModel) { //TODO }
5、@ApiModel：用于JavaBean上面，表示一个JavaBean
@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息 （这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）
6. @ApiModelProperty：用在JavaBean的属性上面，说明属性的含义
@ApiModel和 @ApiModelProperty举例：
@ApiModel("修改密码所需参数封装类") public class PasswordModel { @ApiModelProperty("账户Id") private String accountId; //TODO }
总结：API文档浏览地址
配置好Swagger2并适当添加注解后，启动SpringBoot应用，
访问http://localhost:8080/swagger-ui.html 即可浏览API文档。
另外，我们需要为了API文档的可读性，适当的使用以上几种注解就可以。
四、把Swagger2的API接口导入ApiPost（postman同理）
1、访问http://ip:端口/swagger-ui.html 文档的首页，复制下面这个地址，浏览器打开后，直接Ctrl+S 保存json文件到电脑
2.打开ApiPost
