搭建单机swagger服务
前言
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：多个请求参数
