Spring boot 整合 swagger3

现在的项目大多数都是前后台分离，这就要求前后端对于数据的请求与响应必须统一，以往各自开发都知道自己需要的是什么参数，但是当前后台分开的时候，接口文档就十分有必要了，于是乎，swager应运而生。

引入依赖

整合swagger3其实很简单，只需要引入相关依赖，如下：

    io.springfoxspringfox-boot-starter3.0.0
 

常用注解说明

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

添加启动开关以及对应的实体类和接口

启动类上添加注解@EnableOpenApi即可

package com.yml.user.center;import com.yml.entity.UserPo;
 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiOperation;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 import springfox.documentation.oas.annotations.EnableOpenApi;/*** @author Menglin.Yang* @description* @createTm 2021/11/7 0007*/
 @SpringBootApplication
 @EnableDiscoveryClient
 @RestController
 @EnableOpenApi
 @Api(tags = "用户中心")
 public class UserServerApplication {public static void main(String[] args) {SpringApplication.run(UserServerApplication.class,args);}@PostMapping("/getUser")@ApiOperation("获取用户信息")public UserPo getUser(UserPo po){return po;}
 }

对应实体类

package com.yml.entity;import io.swagger.annotations.ApiModel;
 import io.swagger.annotations.ApiModelProperty;import java.io.Serializable;/*** @author Menglin.Yang* @description* @createTm 2021/11/14 0014*/
 @ApiModel("用户信息")
 public class UserPo implements Serializable {@ApiModelProperty("id")private Long id;@ApiModelProperty("用户名")private String username;public Long getId() {return id;}public void setId(Long id) {this.id = id;}public String getUsername() {return username;}public void setUsername(String username) {this.username = username;}
 }

访问

然后浏览器访问 localhost:8080/swagger-ui

自定义配置

package com.yml.user.center;import io.swagger.annotations.ApiOperation;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.ApiInfoBuilder;
 import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.service.ApiInfo;
 import springfox.documentation.service.Contact;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;/*** @author Menglin.Yang* @description* @createTm 2021/11/14 0014*/
 @Configuration
 public class Swagger3Config {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("用户服务接口文档").description("更多请咨询服务开发者YML。").contact(new Contact("YML", "https://www.baidu.com", "yml@xxxx.com")).version("1.0").build();}
 }

使用 bootstrap ui

引入依赖

    com.github.xiaoyminswagger-bootstrap-ui1.9.6
 

浏览器输入 localhost:8080/doc.html