简介
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。
swagger的接口文档有两种风格，分别为水平列表和树形分类。
旧版UI
增强UI
接口详情
其中，水平列表风格在接口多起来后，就很不友好，找起接口来比较麻烦，所以这里将介绍树形分类风格的swagger。废话不多说走起。。。
目录结构
首先，案例是基于springboot web项目进行讲解的，目录结构如下：
目录结构
步骤一 引入依赖
<!-- swaggwe-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger核心包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swaggwe增强ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
步骤二 新建swagger配置类
@Configuration
//启用swagger2
@EnableSwagger2
//启用swagger增强UI
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
//这里写的是API接口所在的包位置
.apis(RequestHandlerSelectors.basePackage("com.ypk.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
}
步骤三 编写接口
@Api(tags = "测试swagger")
@RestController
@RequestMapping(value = "/swagger")
public class SwaggerController {
@ApiOperation(value = "获取用户信息")
@GetMapping(value = "/info")
public Result<User> getInfo() {
return Result.<User>successResponse();
}
@ApiOperation(value = "获取列表数据")
@GetMapping(value = "/list")
public Result<List<User>> getList() {
return Result.<List<User>>successResponse();
}
}
为了更好地做演示，这里建了两个javabean类，Result和User。
@ApiModel(value = "结果对象")
@Data
@AllArgsConstructor
public class Result<T> {
private static final String successMsg = "请求成功";
private static final String failMsg = "请求失败";
private int status;
private String message;
private T data;
public static <T> Result<T> successResponse() {
return new Result<T>(200, successMsg, null);
}
public static <T> Result<T> successResponse(T data) {
return new Result<T>(200, successMsg, data);
}
public static <T> Result<T> failResponse() {
return new Result<T>(-1, failMsg, null);
}
public static <T> Result<T> failResponse(int status, T data) {
return new Result<T>(status, failMsg, data);
}
public static <T> Result<T> failResponse(String message, T data) {
return new Result<T>(-1, message, data);
}
public static <T> Result<T> failResponse(int status, String message, T data) {
return new Result<T>(status, message, data);
}
}
@ApiModel(value = "用户视图")
@Data
public class User {
private int id;
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "年龄")
private int age;
}
这里有关swagger的注解使用不明白的道友，请看我的另一篇文章《注解篇-Swagger常用注解详解》，@Api…开头的都是swagger的注解。
步骤四 启动项目
启动项目后，在浏览器地址栏访问localhost:8080/doc.html
文档主页：
文档主页
单个接口详情：
单个接口
接口详情
导出离线文档
若不想开放文档地址，也可导出离线文档供更多成员使用，导出的离线文档是Markdown格式的文档，可以使用Markdown转word工具转为word文档，更能使更多人易于理解。
离线文档
这里再介绍一款在线Markdown转word工具：
http://tools.jb51.net/aideddesign/markdown_tool
在线Markdown
新建一个空白word文档，使用 保留源格式 方式粘贴即可。
保存word
至此，springboot整合swagger增强版UI接口文档就完事了；
若文章对道友您有用，记得点赞评论加关注我哦！！！
网友评论