Swagger2介绍+与SpringMVC整合

最新推荐文章于 2022-10-26 20:08:01 发布

转载最新推荐文章于 2022-10-26 20:08:01 发布 · 163 阅读

0 ·

CC 4.0 BY-SA版权

原文链接：https://my.oschina.net/wuweixiang/blog/1865969

2019独角兽企业重金招聘Python工程师标准>>>

前言

本文简单介绍了SpringMVC项目中集成swagger的流程和一些注意点。如果想深入分析项目源码，了解更多内容，见参考资料。

What Is Swagger?

Swagger是一套围绕OpenAPI规范构建的开源工具，可以帮助您设计，构建，记录和使用REST API。主要的Swagger工具包括：

Swagger Editor - 基于浏览器的编辑器，您可以在其中编写OpenAPI规范。
Swagger UI - 将OpenAPI规范呈现为交互式API文档。
Swagger Codegen - 从OpenAPI规范生成服务器存根和客户端库。

Spring集成Swagger流程

1、添加依赖

       <!-- swagger2 begin -->
        <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>1.0.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
        <!-- swagger2 end -->

2、创建swagger2配置类

package com.zhuoan.webapp.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * On shihao.xue to decorate
 *
 * @author weixiang.wu
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

/**
 * 对所有api扫描配置:controller路径  ,分隔
 */
private static final String BASE_PACKAGE = "com.shuziyu.webapp.controller.xxx,com.shuziyu.webapp.controller.encrypt";

/**
 * Swagger2的配置文件：内容、扫描包等
 *
 * @return the docket
 */
@Bean
public Docket createApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        .apis(Swagger2Config.basePackage(BASE_PACKAGE))
        .paths(PathSelectors.any())
        .build();
}

/**
 * Predicate that matches RequestHandler with given base package name for the class of the handler method.
 * This predicate includes all request handlers matching the provided basePackage
 *
 * @param basePackage - base package of the classes
 * @return this
 */
public static Predicate<RequestHandler> basePackage(final String basePackage) {
    return input -> declaringClass(input).transform(handlerPackage(basePackage)).or(true);
}
/**
 * @param input RequestHandler
 * @return Optional
 */
private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
    return Optional.fromNullable(input.declaringClass());
}


@Bean
public RequestMappingInfoHandlerMapping requestMapping() {
    return new RequestMappingHandlerMapping();
}
/**
 * 处理包路径配置规则,支持多路径扫描匹配以逗号隔开
 *
 * @param basePackage 扫描包路径
 * @return Function
 */
private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
    return input -> {
        for (String strPackage : basePackage.split(",")) {
            boolean isMatch = input.getPackage().getName().startsWith(strPackage);
            if (isMatch) {
                return true;
            }
        }
        return false;
    };
}

    /**
     * 构建api文档的详细方法
     *
     * @return ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            //页面标题
            .title("Spring mvc 测试使用 Swagger2 构建Api")
            //创建人
            .contact(new Contact("name", "url", "email"))
            //版本号
            .version("1.0.0")
            //描述
            .description("API 描述")
            .build();
    }
}

如上代码所示，通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

3、开启swagger2

在dispatcher-servlet.xml文件里添加如下配置

   <context:component-scan base-package="com.zhuoan.webapp.controller" />
   
   <!-- 引入swagger相关 ，注意静态资源文件映射是否打开-->
    <mvc:resources mapping="com.swagger-ui.html" location="classpath:/META-INF/resources/" />
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />

4、给接口类添加注解

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

@Controller
@RequestMapping("/say")
@Api(value = "SayController|一个用来测试swagger注解的控制器")
public class SayController {
    
    @ResponseBody
    @RequestMapping(value ="/getUserName", method= RequestMethod.GET)
    @ApiOperation(value="根据用户编号获取用户姓名", notes="test: 仅1和2有正确返回")
    @ApiImplicitParam(paramType="query", name = "userNumber", value = "用户编号", required = true, dataType = "Integer")
    public String getUserName(@RequestParam Integer userNumber){
        if(userNumber == 1){
            return "张三丰";
        }
        else if(userNumber == 2){
            return "慕容复";
        }
        else{
            return "未知";
        }
    }
    
    @ResponseBody
    @RequestMapping("/updatePassword")
    @ApiOperation(value="修改用户密码", notes="根据用户id修改密码")
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="query", name = "userId", value = "用户ID", required = true, dataType = "Integer"),
        @ApiImplicitParam(paramType="query", name = "password", value = "旧密码", required = true, dataType = "String"),
        @ApiImplicitParam(paramType="query", name = "newPassword", value = "新密码", required = true, dataType = "String")
    })
    public String updatePassword(@RequestParam(value="userId") Integer userId, @RequestParam(value="password") String password, 
            @RequestParam(value="newPassword") String newPassword){
      if(userId <= 0 || userId > 2){
          return "未知的用户";
      }
      if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){
          return "密码不能为空";
      }
      if(password.equals(newPassword)){
          return "新旧密码不能相同";
      }
      return "密码修改成功!";
    }
}

这样swagger2与SpringMVC 就集成完毕了。

注意，引入

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

访问主页面：http://localhost:8080/swagger-ui.html访问swagger专有jsonAPI： http://localhost:8080/v2/api-docs

全部注释列表

@Api Api 标记可以标记一个Controller类做为swagger 文档资源，使用方式

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

@ApiOperation每一个url资源的定义,使用方式

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	返回的对象
responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	http的状态码默认 200
extensions	扩展属性

@ApiParam标记 public ResponseEntity createUser(@RequestBody @ApiParam(value = “user”, required = true) User user)

属性名称	备注
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子

@ApiImplicitParam对容器的描述

属性名称	备注
name	属性名称
value	属性值
defaultValue	默认值
allowableValues	可以不可配置
required	是否属性必填
access	不可过多描述
allowMutiple	默认为false
dataType	数据类型
paramType	参数类型

@ApiResponse

属性名称	备注
code	http的状态码
message	描述
response	默认响应类 Void
reference	参考ApiOperation中配置
responseHeaders	参考 ResponseHeader 属性配置说明
responseContainer	参考ApiOperation中配置

@ResponseHeader(name=”head1”,description=”response head conf”)

属性名称	备注
name	响应头名称
description	头描述
response	默认响应类 Void
responseContainer	参考ApiOperation中配置

文档编写规范建议

model的描述

@ApiModel(description = “我是描述”,value = “用户”) 对实体的描述

description：在v2/api-docs的实体看到描述， value的值在@ApiImplicitParam注解中的dataType可用，

@ApiModelProperty(value = “用户姓名”,required = true,dataType = “String”) private String name; 对字段的描述

value：1，入参和出参的ModelModel Schema选项卡可见，2，在v2/api-docs的实体字段描述可见 required：该属性是否必填写 dataType:该字段的数据类型

controller的描述

@Api(value = “API”, description = “用户接口详情”,tags=”A”) 对controler的描述

value:访问某个controller的url的根路径值 description：对于该controller的的大概描述 tags:把api接口进行分分组

@ApiOperation(value = “获取用户详细信息”, notes = “根据url的id来获取用户详细信息”,httpMethod =”GET”) 对该方法的描述

value:主页面中对该接口的描述，位置在接口的最右边 notes：点开接口后，第一段描述。 httpMethod:HTTP请求的动作名，可选值有：”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。

@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “String”, paramType = “path”) 对参数的描述，如果多个参数需要用@ApiImplicitParams对其进行包裹

name:参数名称 value：参数的简短描述 required:是否必须传递的参数 dataType:参数类型，可以为类名，也可以为基本类型（String，int，Boolean） paramType：参数的传入（请求）类型，可选的值有path, query, body, header or form。（如果在路径中提取参数用path比如:在／A／{XXX}路径中得到XXX的值）

@ApiParam(name = “user”, value = “userValue”, required = true) 对参数元信息的说明，一般这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下，和ApiImplicitParam注解类似

required:该参数是否必填 value:该参数的简短介绍

@ApiResponse(code = 200, message = “Successful — 请求已完成”) 返回状态码的描述,如果有多个可以使用@ApiResponses注解进行包裹

code:服务器返回的状态码 message：服务器返回状态码的简短说明

转载于:https://my.oschina.net/wuweixiang/blog/1865969