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是基于 The Apache License, Version 2.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的实现
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 org.springframework.context.annotation.Bean; import org.springframework.context.annotation.ComponentScan; import org.springframework.context.annotation.Configuration; import org.springframework.stereotype.Component; import org.springframework.web.context.request.async.DeferredResult; import org.springframework.web.servlet.config.annotation.EnableWebMvc; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.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 访问路径: * http://IP:port/{context-path}/swagger-ui.html * eg:http://localhost:8080/vrworldapi/api/swagger-ui.html */ @Component @EnableSwagger2 @ComponentScan(basePackages = {"gevek.vr.controller"}) @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("gevek.vr.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("连飞电竞RESTful APIs") .termsOfServiceUrl("http://www.lfly.com") .contact("连飞电竞") .version("1.1") .license("Apache 2.0") .licenseUrl("http://www.apache.org/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
在pom.xml中引入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 的默认访问地址是 http://${host}:${port}/docs.html,而美化的界面如下:
和
2、Swagger-Bootstrap-UI
Swagger-Bootstrap-UI与swagger-ui-layer大致相同,需要引入的依赖如下:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.6</version> </dependency>
swagger-bootstrap-ui默认访问地址是:http://${host}:${port}/doc.html。
需要注意:swagger封装给出的请求地址默认是/v2/api-docs,所以swagger-bootstrap-ui调用后台也是/v2/api-docs,不能带后缀,且需返回json格式数据,框架如果是spring boot的可以不用修改,直接使用,如果是Spring MVC在web.xml中配置了DispatcherServlet,则需要追加一个url匹配规则,如下:
<servlet> <servlet-name>cmsMvc</servlet-name> <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class> <init-param> <param-name>contextConfigLocation</param-name> <param-value>classpath:config/spring.xml</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <!--默认配置,.htm|.do|.json等等配置--> <servlet-mapping> <servlet-name>cmsMvc</servlet-name> <url-pattern>*.htm</url-pattern> </servlet-mapping> <!-- 配置swagger-bootstrap-ui的url请求路径--> <servlet-mapping> <servlet-name>cmsMvc</servlet-name> <url-pattern>/v2/api-docs</url-pattern> </servlet-mapping>
效果图如下: