swagger2使用步骤

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

注意：
生产环境是不允许查看swagger的,可以使用@Profile({“dev”, “test”})
详细禁用方式查看：
https://blog.csdn.net/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);}

步骤简要

pom导入
swagger配置类
controller:
类名上：@Api(description = “系统用户相关接口”)
方法上：@ApiOperation(“系统注册登录接口”)
入参DTO实体类以及成员变量中的实体类：
类名上：@ApiModel(value = “系统用户”)
变量上：@ApiModelProperty(value = “*审核状态”, example = “2”, allowableValues = “2, 3”, required = true)
Result实体类及出参VO实体类：
类名上：@ApiModel(“响应结果”)
变量上：@ApiModelProperty(value = "接口返回状态码; ", example = “1”, position = 0)

注意事项

接口的出参入参尽量使用实体类对象，不要使用Map
返回的Result一定要标记泛型，否则生成的接口文档data是空对象,
如：
public Result submitLogin(UserDTO UserDTO) {}
入参实体类中@ApiModelProperty的required :true或flase时，暂未发现UI界面此配置的展示，因此在value配置中标明，如：
@ApiModelProperty(value = “*人员ID(修改时必填)”, example = “10086”, required = false, position = 1)
@ApiModelProperty(value = “*年份”, example = “2016”, required = true, position = 1)
入参字段描述也在value配置中标明
@ApiModelProperty(value = “接口返回状态码;1成功;-1失败;-2参数异常”, example = “1”, position = 0)
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*/@Beanpublic 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 注解的参数组成的请求参数列表

swagger2使用步骤相关推荐

SpringBoot集成Swagger2、Swagger2和Swagger3的区别Swagger的注解学习
Swagger的介绍 Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新. 随着前后端 ...
技术2---swagger2
文章目录一.前言二.swagger2是什么? 三.swagger常用注解四.swagger2使用步骤 1.创建maven工程swagger-demo,并在pom.xml引入依赖 2.创建实体类U ...
springboot集成swagger2多模块中文配置详细步骤，解决集成mybatis或mybatis-plus无法正常使用问题
springboot集成swagger2多模块中文配置详细步骤,解决集成mybatis或mybatis-plus无法正常使用问题参考文章: (1)springboot集成swagger2多模块中文配 ...
03、Swagger2和Springmvc整合详细记录（爬坑记录）
时间内容备注 2018年6月18日基本使用 spirngmvc整合swagger2 开始之前这个系列博文基本是,在项目的使用中一些模块的内容记录,但是后期逐渐优化,不单单是整合内容. swagg ...
Spring Boot（九）Swagger2自动生成接口文档和Mock模拟数据
一.简介在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
Spring3集成Swagger2遇到问题总结
为什么要用Swagger? 首先说一下需求:最近公司要开发一个小程序,我负责后台的接口开发.公司为了规范接口文档要统一使用YAPI 进行管理.YAPI支持Swagger 格式json文件导入,所以准备 ...
idea swagger生成接口文档_Spring Boot（九）Swagger2自动生成接口文档和Mock模拟数据...
一.简介在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
使用Jenkins打包和部署Maven工程步骤详解
上节已部署jenkins: https://blog.csdn.net/weixin_39816740/article/details/104943258 并准备好一个maven项目发布到码云上节 ...
SpringBoot整合Swagger2
整合Swagger2 1.Swagger介绍前后端分离开发模式中,api文档是最好的沟通方式. Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web ...

swagger2使用步骤

步骤简要

注意事项

swagger2使用步骤相关推荐

最新文章

热门文章