swagger2使用步骤

本人是springboot集成swagger2的环境。
并且项目中过滤器会对请求进行拦截，因此需要对一下URI放行：

注意：
生产环境是不允许查看swagger的,可以使用@Profile({“dev”, “test”})
详细禁用方式查看：
https://blog.youkuaiyun.com/LiuKingJia/article/details/89878320

 // swagger 相关接口
    String[] includeUrlSwagger = new String[]{"/webjars", "/v2", "/swagger-resources", "/swagger-ui"};
    
    String uri = request.getRequestURI();
    for (String swaggerUrl: includeUrlSwagger) {
            if (uri.contains(swaggerUrl)) {
                isNeedFilter = false;
                break;
            }
     }       
 	if (!needFilter) {
            //不需要过滤直接传给下一个过滤器
            filterChain.doFilter(requestWrapper != null ? requestWrapper : request, servletResponse);
    } 

步骤简要

1. pom导入

2. swagger配置类

3. controller:
   类名上：@Api(description = “系统用户相关接口”)
   方法上：@ApiOperation(“系统注册登录接口”)

4. 入参DTO实体类 以及成员变量中的实体类：
   类名上：@ApiModel(value = “系统用户”)
   变量上：@ApiModelProperty(value = “*审核状态”, example = “2”, allowableValues = “2, 3”, required = true)

5. Result实体类 及出参VO实体类：
   类名上：@ApiModel(“响应结果”)
   变量上：@ApiModelProperty(value = "接口返回状态码; ", example = “1”, position = 0)

**

注意事项

**

1. 接口的出参入参尽量使用实体类对象，不要使用Map

2. 返回的Result一定要标记泛型，否则生成的接口文档data是空对象,
   如：
   public Result submitLogin(UserDTO UserDTO) {}

3. 入参实体类中@ApiModelProperty的required :true或flase时，暂未发现UI界面此配置的展示，因 此在value配置中标明，如：
   @ApiModelProperty(value = “*人员ID(修改时必填)”, example = “10086”, required = false, position = 1)
   @ApiModelProperty(value = “*年份”, example = “2016”, required = true, position = 1)

4. 入参字段描述也在value配置中标明
   @ApiModelProperty(value = “接口返回状态码;1成功;-1失败;-2参数异常”, example = “1”, position = 0)

5. Swagger-UI界面接口参数默认按开头字母排序，如有需求配置position

1.pom依赖

<!-- swagger -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.5.0</version>
</dependency>

<!-- swagger-ui -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.5.0</version>
</dependency>

2.swagger2配置类

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

/**
 * @Description: swagger 配置
 */
@Configuration
@EnableSwagger2
@Profile({"dev", "test"})
public class SwaggerConfig {

    /**
     * 创建Rest Api描述
     * @return
     */
    @Bean
    public Docket createRestApi() {
     	List<ResponseMessage> responseMessageList = new ArrayList<>();
        responseMessageList.add(new ResponseMessageBuilder().code(401).message("未经授权")
                .responseModel(new ModelRef("Result")).build());
        responseMessageList.add(new ResponseMessageBuilder().code(404).message("找不到资源")
                .responseModel(new ModelRef("Result")).build());
        responseMessageList.add(new ResponseMessageBuilder().code(500).message("服务器内部错误")
                .responseModel(new ModelRef("Result")).build());

        return new Docket(DocumentationType.SWAGGER_2)
        		.globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE, responseMessageList)
                .apiInfo(apiInfo())
                .select()                       //按条件指定生成文档接口
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 接口描述
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXXX项目")
                .description("XXXX模块")
                .version("1.0")
                .build();
    }
}

3.注解配置
@Api(description = “管理接口”) :作用在类上面，说命名该controller的作用
@ApiOperation(“添加用户接口”) :作用在方法(具体的接口)上,说明该方法是干什么的接口

POST请求：

@Data
@ApiModel(value = "系统用户", description = "系统用户对象")
public class UserDTO implements Serializable {
	// 用户id
	@ApiModelProperty(
	value = "用户id",
	name = "id",
	example = "3b8f975f932d98a3582d9c629db9",
	required = true)
	@NotNull(message = "用户id为空")
	private String id;
}

有参GET请求：

/**
     * 根据系统模块查询角色列表
     *
     * @param subSystem
     * @return
     */
    @GetMapping("list/{subSystem}")
    @ApiOperation("根据系统模块查询角色列表")
    public Result getRoleListBySystem(
            @ApiParam(
                    value = "系统模块",
                    allowableValues = "1, 2, 3",
                    example = "1",
                    required = true)
            @PathVariable("subSystem") String subSystem) {
    }

Swagger 通过注解定制接口对外展示的信息，这些信息包括接口名、请求方法、参数、返回信息等。更多注解类型：
•	@Api：修饰整个类，描述Controller的作用
•	@ApiOperation：描述一个类的一个方法，或者说一个接口
•	@ApiParam：单个参数描述
•	@ApiModel：用对象来接收参数
•	@ApiProperty：用对象接收参数时，描述对象的一个字段
•	@ApiResponse：HTTP响应其中1个描述
•	@ApiResponses：HTTP响应整体描述
•	@ApiIgnore：使用该注解忽略这个API
•	@ApiError ：发生错误返回的信息
•	@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
•	@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表