简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

swagger的接口文档有两种风格，分别为水平列表和树形分类。

其中，水平列表风格在接口多起来后，就很不友好，找起接口来比较麻烦，所以这里将介绍树形分类风格的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

新建一个空白word文档，使用 保留源格式 方式粘贴即可。

至此，springboot整合swagger增强版UI接口文档就完事了，若文章对道友您有用记得点赞评论加关注我哦！！！