OpenAPI规范3-Swagger2 的美化使用

软件测试君

发布于 2022-01-24 01:32:18

6.7K00

代码可运行

文章被收录于专栏：测试人生测试人生

运行总次数：0

代码可运行

背景

本人自己使用的swagger2.0，鉴于颜值和OpenAPI规范，就想体验下，后续再补充各种情况的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配置及静态配置

  
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("XXXXRESTful APIs")
                .termsOfServiceUrl("http://www.lfly.com")  
                .contact("XXXX")  
                .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/");
 }
}

3、使用注解配置Controller

核心部分，需要为每一个接口配置OpenAPI规范的所有信息。常用注解如下（具体配置参数参见官网）：@Api：修饰整个类，描述Controller的作用

注解名称	描述
@ApiOperation	描述一个类的一个方法，或者说一个接口
@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>