SpringBoot学习要点记录（五）----整合swagger，swagger2注解

一、介绍

swagger是一款API 开发工具，可以根据resutful风格生成接口开发文档，并且支持做测试。

二、使用步骤

1.pom文件

<!--引入swagger-->
<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.配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     *
     * @return
     */

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //这里用的是ApiOperiation注解的被扫描，也可以添加包扫描
                //.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger和springBoot整合")
                .description("swagger的API文档")
                .version("1.0")
                .build();
    }
}

3.注解修饰Controller，具体事例见下文
4.访问http://localhost:8080/swagger-ui.html#/，注意修改端口

三、使用示例

说明：测试使用，仅供参考。
实体类：

@Data
public class User {
    private Long id;
    private String username;
    @JsonIgnore
    private String password;
    private String email;
    private Integer age;
    private Boolean enabled;
}

Controller类

@RestController
@Api(tags = "用户接口",description = "UserController描述")
@RequestMapping("/users")
public class UserController {

	@ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
	@RequestMapping(method = RequestMethod.GET)
	public List<User> getAll() {
		ArrayList<User> users = new ArrayList<>();
		User user1  = new User();
		user1.setUsername("张三");
		User user2  = new User();
		user2.setUsername("李四");
		users.add(user1);
		users.add(user2);
		return users;
	}

	@ApiOperation(value = "获取用户", notes = "根据id获取用户")
	@RequestMapping(value="/{id}",method=RequestMethod.GET)
	@ApiImplicitParams({
			@ApiImplicitParam(name = "id", value = "用户ID",required = true, paramType="path", dataType = "Long")
	})
	@ApiResponses({
		@ApiResponse(code=400,message="请求参数没填好"),
		@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
	})
	public User getUser(@PathVariable Long id) {
		User user = new User();
		user.setUsername("张飞");
		return user;
	}

	@ApiOperation(value = "更新用户", notes = "根据id更新用户")
	@RequestMapping(value="/{id}",method=RequestMethod.PUT)
	public String putUser(@PathVariable Long id,  User user) {
		return "success";
	}
	
	@ApiOperation(value = "新增用户", notes = "根据User对象创建用户")
	@RequestMapping(method = RequestMethod.POST)
	public String postUser(User user) {
		return "success";
	}
	
	@ApiOperation(value = "删除用户", notes = "根据id删除用户")
	@RequestMapping(value="/{id}", method=RequestMethod.DELETE)
	public String deleteUser(@PathVariable Long id) {
		return "success";
	}
}

测试网址：http://localhost:8080/swagger-ui.html

Restful规范
请求方式为以下五种
GET：读取（Read）
POST：新建（Create）
PUT：更新（Update）
PATCH：更新（Update），通常是部分更新
DELETE：删除（Delete）

生产环境禁用swagger方法
方式一：
1.配置类上添加@ConditionalOnProperty(name = “swagger.enable”, havingValue = “true”)
2.application-dev.yml配置文件添加swagger.enable = fasle，开发环境设置为true即可

swagger:
  enable: false

方式二：
在配置类上添加@Profile({“dev”,“test”})
表示只会在开发环境和测试环境才会启用。

四、注解含义

注解	说明
@EnableSwagger2	作用：开启Swagger注解 位置：Swagger配置类上 参数：无
@Api	作用：标识Swagger识别的类 位置：Controller类上 参数：value:值            tags:分组            description:描述
@ApiIgnore	作用：屏蔽显示某个Controller 位置：Controller类上或方法上（只屏蔽方法）
@ApiOperation	作用：标识Swagger识别的方法 位置：方法上 参数：tags:分组（可以将方法划分为一组进行展示，可跨Controller）            value:描述            notes:说明（这个是在详情里点开才会展示的）
@ApiImplicitParams	作用：用在请求的方法上，表示一组参数说明 位置：方法上 参数：@ApiImplicitParam
@ApiImplicitParam	作用：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 位置：方法上，@ApiImplicitParams注解中 参数：name:参数名            value:参数的汉字说明、解释            required:参数是否必须传            dataType:参数类型，默认String            paramType:参数放在哪个地方，如path、query、form、header、body
@ApiResponses	作用：用作返回值的描述，修饰方法的返回值集合 位置：方法上 参数：@ApiResponse
@ApiResponse	作用：一般用于表达一个错误的响应信息 位置：方法上 参数： code：数字，例如400            message：信息，例如"请求参数没填好"            response：抛出异常的类
@ApiModel	作用：表示一个返回响应数据的信息 位置：类上，一般为响应类 参数：description：描述
@ApiModelProperty	作用：描述类的属性 位置：类的属性上 参数：value：值
@JsonIgnore	作用：忽略某一字段，不响应 位置：类的属性上

参考：https://blog.csdn.net/jiangyu1013/article/details/83107255

五、测试问题记录

1.问题：“Failed to convert value of type ‘java.lang.String’ to required type ‘java.lang.Long’; nested exception is java.lang.NumberFormatException: For input string: “{id}””,

原因：@ApiImplicitParam没有加paramType=“path”，加上后测试正常

	@ApiOperation(value = "获取用户", notes = "根据id获取用户")
	@RequestMapping(value="/{id}",method=RequestMethod.GET)
	@ApiImplicitParams({
			@ApiImplicitParam(name = "id", value = "用户ID",required = true, paramType="path", dataType = "Long")
	})
	public User getUser(@PathVariable Long id) {
		System.out.println(id);
		User user = new User();
		user.setUsername("张飞");
		return user;
	}