在springboot中添加swagger文档

问题提出
在后端代码编写完成后，需要生成接口文档，并且进行接口测试。图形界面的postman和命令行curl都是较好的接口调用方法，但没有接口的详细说明。
swagger就解决了在代码开发过程中对接口说明，接口参数说明，并且能够提供页面进行接口测试。

swagger的使用

在springboot中，引入第三方库常规三板斧：

1. 在pom文件中，引入maven依赖包
2. 编写配置文件swaggerconfig.java
3. 代码中使用swagger注释

1. 项目中添加swagger依赖

<!--Swagger-UI API文档生产工具-->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.7.0</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.7.0</version>
</dependency>

2. 添加Swagger-UI的配置

Swagger对生成API文档的范围有三种不同的选择

• 生成指定包下面的类的API文档
• 生成有指定注解的类的API文档
• 生成有指定注解的方法的API文档

package com.macro.mall.tiny.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
               .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
                //为有@Api注解的Controller生成API文档
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("demo")
                .contact("demo")
                .version("1.0")
                .build();
    }
}

3. 代码中使用swagger注释

3.1 swagger常用注解

• @Api：用于修饰Controller类，生成Controller相关文档信息
• @ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息
• @ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息
• @ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息

3.2 输入输出的实体类添加注解: UserCreateParam.java

这里使用了@ApiModelProperty()

@Data
public class UserCreateParam implements Serializable {

    private static final long serialVersionUID = 3932926461826363655L;

    @NotNull(message = "登录账号不可为空")
    @ApiModelProperty(value = "登录账号，必填", required = true)
    private String loginName;

    @NotNull(message = "登录密码不可为空")
    @ApiModelProperty(value = "登录密码，必填", required = true)
    private String passwd;

    @NotNull(message = "用户名称不可为空")
    @ApiModelProperty(value = "用户名称，必填", required = true)
    private String name;
}

3.3 Controller层添加注解: UserController.java

@Api(tags = "UserController", description = "用户信息")
@RestController
@RequestMapping("/user")
public class UserController {

    @Autowired
    private UserService userService;

    @ApiOperation("创建用户")
    @PostMapping(value = "/create")
    public RespBody create(@RequestBody UserCreateParam userCreateParam) {
        return userService.create(userCreateParam);
    }

	@ApiOperation("查询用户")
    @GetMapping(value = "/get/{id}")
    public RespBody get(@PathVariable("id") @ApiParam(name="id", value = "用户id，必传")  Integer id) {
        return userService.get(id);
    }

提问

问题1：swagger2.0 升级到swagger3.0, 两者有什么区别

问题2：Azure APIM怎样和swagger文档结合使用