Swagger

Swagger

学习目标：

• 了解Swagger的概念及作用
• 掌握在项目中集成Swagger自动生成API文档

一、Swagger解决的问题

前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发。
利用实时跟踪最新的API，降低集成风险

二、使用Swagger

要求：jdk 1.8 + 否则swagger2无法运行

1.maven依赖：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

2.编写Controller

3.我们需要编写一个配置类-SwaggerConfig来配置 Swagger

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {  
}

4.访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示

application.yml
	spring: 
		profiles: 
		 active: dev

@Bean
public Docket docket(Environment environment) {
	//表示扫描到application.yml文件中的profiles.active的值如果是“dev”或"test"，
	//则flage为true，然后将启用对应的application-dev.yml或application-test.yml中的server.port值显示对应端口下的swagger环境。

   // 设置要显示swagger的环境
   Profiles of = Profiles.of("dev", "test");
   // 判断当前是否处于该环境
   // 通过 enable() 接收此参数判断是否要显示
   boolean flage = environment.acceptsProfiles(of);
   
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .enable(flage) //配置是否启用Swagger，如果是false，在浏览器将无法访问
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/kuang/**"))
      .build();
}

作用：通过配置appliction.yml中的spring.profiles.active为prod,让项目上线时不实现swagger环境，使swagger环境只出现在开发和测试的环境下。

配置API分组

如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}

如何配置多个分组？配置多个分组只需要配置多个docket即可：

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

常用注解

//控制层——@Api，@ApiOperation，（@ApiParam和@RequestParam）
	//跨域问题（使用vue+springboot时src读不出来）
	@CrossOrigin
	//控制层
	@Controller
	//映射请求地址
	@RequestMapping("address")
	@Api(tags = "123")
	public class AddressController {
	//方法参数不为对象，使用@ApiParam时需要搭配@RequestParam使用
		@ApiOperation("通过父节点ID查找地址信息")
	    @GetMapping("/findAddressesByParentId")
	    @ResponseBody
	    public List<Address> findAddressByParentId(@ApiParam(name = "addressId",value = "789") @RequestParam(required = false) Long addressId){
	        List<Address> addressByParentId = addressService.findAddressByParentId(addressId);
	        return addressByParentId;
	    }
	
	//方法参数为对象时需不需要加@ApiParam，但是要在实体类的属性上加入@ApiModelProperty注解
		@ApiOperation("12346")
	    @PostMapping("/findAddressesByParentId3")
	    @ResponseBody
	    public Address findAddressByParentId2(Address address){
	        return address;
	    }
	}
//实体类中使用注解的地方——@ApiModel，@ApiModelProperty。
	//lombok
	@Data
	@NoArgsConstructor
	@AllArgsConstructor
	//jpa实体类
	@Entity
	@Table(name = "address")
	@ApiModel(description = "地址实体类")
	public class Address implements Serializable {
		@Id
	    @GeneratedValue(strategy = GenerationType.IDENTITY)
	    @ApiModelProperty(value = "地址ID")
	    private Long addressId;
	}

实体配置

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

@ApiModel("用户实体")
public class User {
   @ApiModelProperty("用户名")
   public String username;
   @ApiModelProperty("密码")
   public String password;
}

只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中

@RequestMapping("/getUser")
public User getUser(){
   return new User();
}