一、Swagger介绍

Swagger是一个开源文档生成器，可以方便的用来生成OpenAPI规格的接口文档，支持Go、Python、Haskell、Java等多种语言，同时支持在线调试接口。

官网：
https://swagger.io

Swagger 工具集包含：
? Swagger Editor – 在线编写 OpenAPI 规范的编辑器
? Swagger UI – 使用 OpenAPI 规范生成的交互式文档
? Swagger Codegen – 使用 OpenAPI 规范分别生成客户端/服务器代码（Server-stub）的工具

同类型的工具还有：

• docway
  

附：OpenAPI 中文文档：https://fishead.gitbooks.io/openapi-specification-zhcn-translation/content/versions/3.0.0.zhCN.html#oasDocument

二、java下的使用

1. 加入依赖

在Springboot环境下的使用十分简单，只需要加入依赖：

<!-- swagger-ui -->
        <dependency>![在这里插入图片描述](https://img-blog.csdnimg.cn/20200927135341240.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3h1bmRo,size_16,color_FFFFFF,t_70#pic_center)

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

2. 书写SwaggerConfig文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket ProductApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.genericModelSubstitutes(DeferredResult.class)
				.useDefaultResponseMessages(false)
				.forCodeGeneration(false)
				.pathMapping("/")
				.select()
				.build()
				.apiInfo(productApiInfo());
	}

	private ApiInfo productApiInfo() {
		ApiInfo apiInfo = new ApiInfo("XXX系统数据接口文档",
				"文档描述。。。",
				"1.0.0",
				"API TERMS URL",
				"联系人邮箱",
				"license",
				"license url");
		return apiInfo;
	}
}

启动Springboot项目后，就可以通过 http://localhost:8080/swagger-ui.html：
来访问接口：

3. 接口注解

2.3.1 controller上的注解

@Api(value="用户controller",tags={"用户操作接口"})
@Controller
@RequestMapping("web/user")
public class UserController {

}

2.3.2 方法上的注解

    @GetMapping("/userInfo")
    @ResponseBody
    @ApiOperation(value = "查询个人信息", tags = {"返回用户信息"}, notes = "提交json格式")
    public Result userInfo(@ApiParam(name="phone",value="用户手机号",required=true)String phone) {
    	Result result = new Result();
        return result;
    }

2.3.3 实体类上的注解

@ApiModel(description="登录请求参数")
public class UserLoginDto {

    @ApiModelProperty(value="用户电话", required=true)
    private String phone;

    @ApiModelProperty(value="密码", required=true)
    private String password;

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

}

2.3.4 常用注解说明

• @Api() 用于类，表示swagger的注解资源
• @ApiOperation() 用于方法，表示一个http请求
• @ApiParam()，用于方法的参数，说明字段使用
• @ApiModel()，于用实体类
• @ApiIgnore 用于类、方法、方法参数，表示这个方法或类被忽略
• @ApiImplicitParam() 用于方法，表示单独的请求参数
• @ApiImplicitParams()用于方法，包含多个 @ApiImplicitParam
• @ApiResponses() 用于方法，包含多个 @ApiResponse

三、更换前端UI

默认的swagger-ui不怎么符合国人的审美观。好在有一些好心的开发者提供了更漂亮的API界面，下面简单介绍几款：

1. knife4j

为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui。使用该工具还可以方便的生成md格式接口源文件。
其功能比较多，只更换swagger-ui的话引用：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-ui</artifactId>
    <version>${lastVersion}</version>
</dependency>

或者使用老版本：

        <!-- 引入swagger-bootstrap-ui包 /doc.html-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.1</version>
        </dependency>

界面效果：

2. Swagger-UI-layer

地址： https://gitee.com/caspar-chen/Swagger-UI-layer
引用：

<dependency>
  <groupId>com.github.caspar-chen</groupId>
  <artifactId>swagger-ui-layer</artifactId>
  <version>${last-version}</version>
</dependency>

效果：

doc访问地址： http://****/docs.html

3. tennetcn

引用：

<dependency>
  <groupId>com.tennetcn.free</groupId>
  <artifactId>think-swagger-ui-starter</artifactId>
  <version>0.0.4</version>
</dependency>

效果：

4. swagger-mg-ui

引用：

<!-- https://mvnrepository.com/artifact/com.zyplayer/swagger-mg-ui -->
<dependency>
    <groupId>com.zyplayer</groupId>
    <artifactId>swagger-mg-ui</artifactId>
    <version>1.0.6</version>
</dependency>

效果：

5. swagger-document-ui

引用：
移除官方 UI 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox.version}</version>
</dependency>

添加 swagger-document-ui 依赖

<dependency>
    <groupId>cn.javaer.springfox</groupId>
    <artifactId>swagger-document-ui</artifactId>
    <version>1.0.2</version>
</dependency>

开源地址：https://gitee.com/cn-src/swagger-document-ui
效果：