概述
Java-springBoot+swaggerUI2使用指南
- 前言
- 一、什么情况下使用？
- 二、使用步骤
- 1.Maven依赖配置
- 2.使用步骤
- 第一步、添加项目配置
- 第二步、创建controller使用注解，形成接口集合以及接口页面
- 第三步、接口添加参数及返回值
- 第四步、开发配置
- ①.返回结果封装类
- ②.返回封装类对应的Code类
- ④.vo返回前端类
- ⑤.dto接收参数类
前言
Swagger UI2是为了解决程序员日常编写文档的烦恼,而推出的根据注解可以自动生成API文档的框架,也是当下比较好用的API框架
一、什么情况下使用？
可以在前后端分离时,接口较多的情况下使用swaggerUI2
二、使用步骤
1.Maven依赖配置
下面是使用Swagger2所用的依赖：
<!-- swagger2 核心包-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- 这个是原本swagger2UI的jar包但是使用不是特别舒服所以引用下面这个swagger-bootstrap-ui-->
<!-- <dependency>-->
<!-- <groupId>io.springfox</groupId>-->
<!-- <artifactId>springfox-swagger-ui</artifactId>-->
<!-- <version>2.9.2</version>-->
<!-- </dependency>-->
<!-- 使用较为好看的swagger-bootstrap-ui 替代了原有的ui-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.2</version>
</dependency>
2.使用步骤
第一步、添加项目配置
主要代码如下（示例）：
/**
* @Author：zeng
* @Date： created in 20:50 2021/4/10
*/
@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurationSupport {
// api接口包扫描路径
@Value("${swagger.package}")
public String SWAGGER_SCAN_BASE_PACKAGE;
// 接口文档版本
@Value("${swagger.version}")
public String VERSION;
//是否启动swaggerUI
@Value("${swagger.enable}")
public boolean ENABLE;
/**
* 因为 Swagger2的资源文件都是在jar包里面，如果不在此处配置加载静态资源，
* 可能会导致请求http://localhost:端口/doc.html失败
* <!--swagger资源配置-->
* <mvc:resources location="classpath:/META-INF/resources/" mapping="doc.html"/>
* <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
* @param registry
*/
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
//新的swagger-bootstrap-ui对应的api页面
registry.addResourceHandler("doc.html")
//想要使用老版的则打开这个注解,并且注释上面的
//registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
/**
* 返回构建器
* @return
*/
@Bean
public Docket createRestApi() {
//返回响应状态信息统一返回
List<ResponseMessage> responseMessageList = new ArrayList<>();
responseMessageList.add(new ResponseMessageBuilder().code(404).message("未找到资源").responseModel(new ModelRef("AjaxResult")).build());
responseMessageList.add(new ResponseMessageBuilder().code(500).message("服务器内部错误").responseModel(new ModelRef("ApiError")).build());
responseMessageList.add(new ResponseMessageBuilder().code(503).message("服务外部异常").responseModel(new ModelRef("ApiError")).build());
//一个构建器，目的是作为SpringFox框架的主要接口。
return new Docket(DocumentationType.SWAGGER_2)
//请求,对应的状态
.globalResponseMessage(RequestMethod.GET, responseMessageList)
.globalResponseMessage(RequestMethod.POST, responseMessageList)
.globalResponseMessage(RequestMethod.PUT, responseMessageList)
.globalResponseMessage(RequestMethod.DELETE, responseMessageList)
//这里配置文档标题作者版本等信息
.apiInfo(apiInfo())
// base，最终调用接口后会和paths拼接在一起
.pathMapping("/")
// 选择那些路径和api会生成document
.select()
//扫描路径,一般为controller路径
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
//(对指定路径进行监控)过滤的接口
.paths(PathSelectors.any())
.build()
//关闭或启动swagger2UI true开启|false关闭
.enable(ENABLE);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//文档首页标题
.title("接口文档")
//文档简绍
.description("服务端接口文档，服务于程序猿")
//文档创作者
.contact("zeng")
//文档版本
.version(VERSION)
.build();
}
}
@Value注解是引用yml里面的配置用于统一开发,测试,生产中是否使用swaggerUI与版本控制
配置application.yml
swagger:
package: com.*.*.controller
version: 1.0.0
enable: true
com...controller属于自己项目的controller路径
效果1:
此时启动项目在浏览器上面输入http://127.0.0.1:端口/doc.html 就可以看到swagger2页面了.
如图所示:
这时说明swaggerUI文档已经加载成功
第二步、创建controller使用注解，形成接口集合以及接口页面
首先创建controller文件夹，在创建一个UserContoller类
在里面添加方法，在加上地址以及swagger对应注解
/**
* @author Robot
* @date 21/04/20
*/
@Controller
@RequestMapping("user")
@Api(tags = "用户接口集合",value = "用户相关接口的集合")
public class UserController {
@GetMapping("getUser")
@ApiOperation(value="查询用户接口", notes="查询用户信息接口",httpMethod = "GET")
public void getUser(){
}
}
效果图：
第三步、接口添加参数及返回值
在方法中添加username参数，修改注解Controller为RestController
@RestController
@RequestMapping("user")
@Api(tags = "用户接口集合",value = "用户相关接口的集合")
public class UserController {
@GetMapping("getUser")
@ApiImplicitParam(name = "username", value = "用户名", required = true, paramType="query")
@ApiOperation(value="查询用户接口", notes="查询用户信息接口",httpMethod = "GET")
public String getUser(@RequestParam String username){
return username;
}
}
添加@ApiImplicitParam对应接口就会有这个参数描述
调试时的参数
到这一步普通的请求就可以这么使用了，接下来是关于实体类的设置，正式开发的配置了
第四步、开发配置
需要创建四个类
①.返回结果封装类
/**
* 统一API响应结果封装
*
* @author zeng
*/
@ApiModel("统一API响应结果封装")
public class AjaxResult<T> implements Serializable {
/**
* 状态码
*/
@ApiModelProperty(value = "成功失败的标志",required = true)
private final int code;
/**
* 响应信息，用来说明响应情况
*/
@ApiModelProperty(value = "操作响应信息",required = true)
private final String message;
/**
* 响应的具体数据
*/
@ApiModelProperty(value = "响应数据",required = false)
private T data;
public AjaxResult(T data) {
this(ResultCode.SUCCESS, data);
}
public AjaxResult(ResultCode resultCode, T data) {
this.code = resultCode.getCode();
this.message = resultCode.getMsg();
this.data = data;
}
public AjaxResult(ResultCode resultCode) {
this.code = resultCode.getCode();
this.message = resultCode.getMsg();
}
/**
* 返回成功消息
*
* @param data 数据对象
* @return 成功消息
*/
public static <T> AjaxResult<T> success(T data) {
return new AjaxResult<>(ResultCode.SUCCESS, data);
}
/**
* 返回成功消息
*
* @return 成功消息
*/
public static <T> AjaxResult<T> success() {
return new AjaxResult<>(ResultCode.SUCCESS);
}
/**
* 返回失败消息
*
* @param resultCode 自定义对象
* @return 自定义失败消息
*/
public static <T> AjaxResult<T> error(ResultCode resultCode) {
return new AjaxResult<>(resultCode);
}
/**
* 返回警告消息
*
* @param data 数据对象
* @return 警告消息
*/
public static <T> AjaxResult<T> error500(T data) {
return new AjaxResult<>(ResultCode.SYSTEM_ERROR, data);
}
/**
* 返回警告消息
*
* @return 警告消息
*/
public static <T> AjaxResult<T> error500() {
return new AjaxResult<>(ResultCode.SYSTEM_ERROR);
}
/**
* 返回错误消息
*
* @param data 数据对象
* @return 警告消息
*/
public static <T> AjaxResult<T> error400(T data) {
return new AjaxResult<>(ResultCode.ERROR, data);
}
/**
* 返回错误消息
*
* @return 警告消息
*/
public static <T> AjaxResult<T> error400() {
return new AjaxResult<>(ResultCode.ERROR);
}
/**
* 未经过身份认证
* @param <T> 返回值类型
* @return
*/
public static <T> AjaxResult<T> authError(){
return new AjaxResult<T>(ResultCode.AUTH_ERROR);
}
/**
* 未经过身份认证
* @param <T> 返回值类型
* @return
*/
public static <T> AjaxResult<T> authError(T data){
return new AjaxResult<T>(ResultCode.AUTH_ERROR,data);
}
/**
* 资源不存在
* @param <T> 返回值类型
* @return
*/
public static <T> AjaxResult<T> error404(){
return new AjaxResult<T>(ResultCode.NOT_FOUND);
}
/**
* 资源不存在
*
* @param <T> 返回值类型
* @return
*/
public static <T> AjaxResult<T> error404(T data) {
return new AjaxResult<T>(ResultCode.NOT_FOUND, data);
}
/**
* 资源不存在
*
* @param <T> 返回值类型
* @return
*/
public static <T> AjaxResult<T> error503() {
return new AjaxResult<T>(ResultCode.RPC_ERROR);
}
/**
* 资源不存在
*
* @param <T> 返回值类型
* @return
*/
public static <T> AjaxResult<T> error503(T data) {
return new AjaxResult<T>(ResultCode.RPC_ERROR, data);
}
public int getCode() {
return code;
}
public String getMessage() {
return message;
}
public T getData() {
return data;
}
}
②.返回封装类对应的Code类
/**
* 状态处理
* @author zeng
*/
public enum ResultCode {
/**
* 操作成功
*/
SUCCESS(200, "操作成功"),
/**
* 操作失败
*/
ERROR(400, "操作失败"),
/**
* 未经过身份认证
*/
AUTH_ERROR(401, "未经过身份认证"),
/**
* 资源不存在
*/
NOT_FOUND(404, "资源不存在"),
/**
* 服务器异常,请稍后再试
*/
SYSTEM_ERROR(500, "服务器异常,请稍后再试"),
// /**
// * 用户信息解析异常,请稍后再试
// */
// USERPRINCIPAL_RESOLVER_ERROR(50001, "用户信息解析异常,请稍后再试"),
/**
* RPC或其他项目通信调用异常，外部服务异常
*/
RPC_ERROR(503, "外部服务异常"),
;
private final int code;
private final String msg;
ResultCode(int code, String msg) {
this.code = code;
this.msg = msg;
}
public int getCode() {
return code;
}
public String getMsg() {
return msg;
}
}
④.vo返回前端类
/**
* @author zeng
* @date 21/04/20
*/
@ApiModel(value = "用户接口VO类")
public class UserVO {
@ApiModelProperty(value = "用户ID", example = "10", name = "type", required = true)
private Integer id;
@ApiModelProperty(value = "用户名称", example = "xiaoming", name = "type", required = false)
private String name;
@ApiModelProperty(value = "用户年龄", example = "18", name = "type", required = false)
private String age;
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getAge() {
return age;
}
public void setAge(String age) {
this.age = age;
}
@Override
public String toString() {
return "UserDTO{" +
"id=" + id +
", name='" + name + ''' +
", age='" + age + ''' +
'}';
}
}
⑤.dto接收参数类
/**
* @author zeng
* @date 21/04/20
*/
@ApiModel(value = "用户接口DTO类")
public class UserDTO {
@ApiModelProperty(value = "用户ID", example = "10", name = "id", required = true)
private Integer id;
@ApiModelProperty(value = "用户名称",name="name", example = "xiaoming", required = false)
private String name;
@ApiModelProperty(value = "用户年龄", example = "18", name = "age", required = false)
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getAge() {
return age;
}
public void setAge(String age) {
this.age = age;
}
@Override
public String toString() {
return "UserDTO{" +
"id=" + id +
", name='" + name + ''' +
", age='" + age + ''' +
'}';
}
}
目前所有的类已经添加完成
效果图：
最后
以上就是闪闪皮带为你收集整理的Java-spring boot整合swagger2前言一、什么情况下使用？二、使用步骤的全部内容，希望文章能够帮你解决Java-spring boot整合swagger2前言一、什么情况下使用？二、使用步骤所遇到的程序开发问题。
如果觉得靠谱客网站的内容还不错，欢迎将靠谱客网站推荐给程序员好友。
本图文内容来源于网友提供，作为学习参考使用，或来自网络收集整理，版权属于原作者所有。
发表评论 取消回复