​

 前言

Swagger是什么：

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

接口文档的维护一直是我们开发过程中的一个很费时间的工作，每次更新线下文档都需要好多人确认更新，很费时间和精力，我之前的博客也搭建过Yapi接口维护平台，但今天Swagger是一个无需人员维护的自动化的接口在线文档

创建项目

我们用 IDEA自动化创建一个spring boot项目

​

建好项目后引入Swagger的依赖（版本一定要2.5.0以及以上版本! 网上博文大多数引的2.2.2版本的, 这个版本在demo中没有问题, 但是开发中你肯定会引别的插件，2.2.2版本的与feign有冲突! 会报bean创建加载异常!）：

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
复制代码

编写配置文件：

package com.ys.platform.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;


@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        List<Parameter> pars = new ArrayList<Parameter>();
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("安余生 REST API")
                .description("有些人心如草木，向阳而生")
                .termsOfServiceUrl("https://blog.csdn.net/AnNanDu/article/details/105274231")
                .version("1.0")
                .build();
    }

}
复制代码

配置application.yml：

server:
  port: 8181

spring:
  application:
    name: swagger
复制代码

编写Demo类：

package com.ys.swagger.test;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RequestMapping("/test")
@RestController
@Api(value = "测试")
public class DemoController {

    @RequestMapping(value = "/test")
    @ApiOperation(value = "测试功能",notes = "实在")
    public String test(){
        return "test";
    }

    @RequestMapping(value = "/test2")
    @ApiOperation(value = "测试功能2",notes = "实在")
    public String test2(){
        return "test";
    }
}
复制代码

启动项目访问地址：http://127.0.0.1:8181/swagger-ui.html（ip+端口/swagger-ui.html）

​

点击想看的接口查看详情：

​

如果想要测试接口点击Try it out然后点击Execute

​

可以看到上面我们同一个方法但是有七种请求类型，在页面上展示很冗余，这个就需要我们在接口定义的时候定义请求类型了

​

然后我们重启再看一下

​

到这里单机Swagger就搭建完成了

其他参数

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

​