OpenAPI规范3-Swagger2
Info：之前使⽤的swagger是1.0版本，现在想将该规范使⽤到现在的项⽬中时，发现已经是基于OpenAPI 3的2.0版本，并且可以⽐1.0更⽅便的集成使⽤（1.0版本需要将GitHub中的swagger的web部分拷贝到项⽬下，现只需要引⼊maven依赖即可），后续再补充各种情况的demo。
⼀、什么是swagger？
OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基⾦会的⼀个项⽬，试图通过定义⼀种⽤来描述API格式或API定义的语⾔，来规范RESTful服务开发过程。⽬前V3.0版本的OpenAPI规范（也就是SwaggerV2.0规范）已经发布并开源在github上。即swagger2.0是基于 许可的OAS3.0实现。
⼆、为什么要⽤Swagger管理项⽬（Swagger特性）？
Swagger tools提供了多个模块⽤户构建⽂档，不同的模块拥有不同的作⽤，主模块如下：
1、设计接⼝
Swagger Editor：⼀个强⼤的编辑器中设计新的api或编辑现有的api，它可以直观地呈现您的狂妄定义，并提供实时的错误反馈。可以⽀持json和yaml（⼀般使⽤yaml）格式的数据类型。如下图：
2、构建
通过⽣成服务器存根和来⾃swagger的规范的客户端sdk，构建并启⽤OAS/Swagger 的可编程语⾔。
3、Swagger UI
Swagger需要在后台配置对于接⼝的相关信息并使⽤注解的⽅式将信息通过Swagger UI进⾏展⽰，⾃动⽣成了⽤于视觉交互的OAS规范中描述的所有⽂档，所以优点在于实时，减少沟通；缺点也在于使⽤注解的⽅式，过深的与代码本⾝交互。
三、Swagger UI2.0的实现为什么使用bootstrap?
1、引⼊maven依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
2、Swagger配置及静态配置
package gevek.vr.swagger;
import t.annotation.Bean;
import t.annotation.ComponentScan;
import t.annotation.Configuration;
import org.springframework.stereotype.Component;
import org.t.request.async.DeferredResult;
import org.springframework.fig.annotation.EnableWebMvc;
import org.springframework.fig.annotation.ResourceHandlerRegistry;
import org.springframework.fig.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/*
* Restful API 访问路径:
* IP:port/{context-path}/swagger-ui.html
* eg:localhost:8080/vrworldapi/api/swagger-ui.html
*/
@Component
@EnableSwagger2
@ComponentScan(basePackages = {"ller"})
@Configuration
public class RestApiConfig extends WebMvcConfigurationSupport{
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
/*.groupName("⽤户数据模块")*/
.genericModelSubstitutes(DeferredResult.class)
/
/              .genericModelSubstitutes(ResponseEntity.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(false)
.select()
.apis(RequestHandlerSelectors.basePackage("ller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXXXRESTful APIs")
.
termsOfServiceUrl("www.lfly")
.contact("XXXX")
.version("1.1")
.license("Apache 2.0")
.licenseUrl("/licenses/LICENSE-2.0.html")
.build();
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");  registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/
webjars/"); }
}
静态配置说明：静态⽂件swagger-ui的设置路径参见下图：
3、使⽤注解配置Controller
核⼼部分，需要为每⼀个接⼝配置OpenAPI规范的所有信息。常⽤注解如下（具体配置参数参见官⽹）：
@Api：修饰整个类，描述Controller的作⽤
@ApiOperation：描述⼀个类的⼀个⽅法，或者说⼀个接⼝
@ApiParam：单个参数描述
@ApiModel：⽤对象来接收参数
@ApiProperty：⽤对象接收参数时，描述对象的⼀个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使⽤该注解忽略这个API
@ApiClass
@ApiError
@ApiErrors
@ApiParamImplicit
@ApiParamsImplicit
4、效果
具体每个接⼝参数信息如下：
四、Swagger UI的扩展
基于Swagger的注解将API个路径、描述、参数、返回值、异常状况等进⾏描述，swagger UI 模块仅仅是⼀个前端渲染框架。由于swagger默认的UI的样式虽然基于其他⽅式的API⽂件已经⾮常不错了，但是页⾯任然不是特别的美观。于是出现了swagger-ui-layer和Swagger-Bootstrap-UI等框架，其本质
仅仅是⼀个更友好和美观的前端UI界⾯的实现，解析的数据来源于 /v2/api-docs，⽽底层依然依赖于swagger的注解功能。
1、swagger-ui-layer
在l中引⼊swagger 和 swagger-ui-layer和依赖，其他与使⽤swagger2⼀致，maven依赖如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>com.github.caspar-chen</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>0.0.2</version>
</dependency>
需要注意的⼀点是 swagger api 的默认地址是/v2/api-docs 所以swagger-ui-layer也读取的是默认地址， 所以在new Docket()的时候不能指定group参数，否则 swagger api 的地址会在后⾯加⼊group的参数导致swagger-ui-layer不能正确请求到数据。即使⽤⾃定义后的ui不能使⽤分组功能将同⼀类型的api进⾏拆分。
swagger-ui-layer 的默认访问地址是 ${host}:${port}/docs.html，⽽美化的界⾯如下：

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。