zoukankan      html  css  js  c++  java
  • Spring MVC 中使用 Swagger2 构建动态 RESTful API

       当多终端(WEB/移动端)需要公用业务逻辑时,一般会构建 RESTful 风格的服务提供给多终端使用。

       为了减少与对应终端开发团队频繁沟通成本,刚开始我们会创建一份 RESTful API 文档来记录所有接口细节。

       但随着项目推进,这样做所暴露出来的问题也越来越严重。

       a. 接口众多,细节复杂(需考虑不同的 HTTP 请求类型、HTTP 头部信息、HTTP 请求内容..),高质量地创建这份文档本身就是件非常吃力的事。

       b. 不断修改接口实现必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。

       基于此,项目组在早些时间引入了 Swagger,经过几个项目的沉淀,确实起到了很不错的效果。

       Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

       服务的方法、参数、模型紧密集成到服务器端的代码,让维护文档和调整代码融为一体,使 API 始终保持同步。

       本文主要描述 Swagger 与 SpringMVC 的集成过程以及遇到的一些问题,权当抛砖引玉只用,具体项目具体分析。

      

    1. Maven 依赖和最简配置

          <!--restfull APi swagger2-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${swagger.version}</version>
            </dependency>
    
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${swagger.version}</version>
            </dependency>

       Spring-Context  Swagger 配置:

        <!-- swagger2 配置类-->
        <bean id="config" class="com.rambo.spm.core.config.SwaggerConfig"/>
    
        <!-- swagger2 静态资源交由 spring 管理映射(springfox-swagger-ui.jar 为静态资源包)-->
        <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
        <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

       <mvc:resources /> 由 Spring MVC 处理静态资源,并添加一些有用的附加值功能。

       a. <mvc:resources /> 允许静态资源放在任何地方,如 WEB-INF 目录下、类路径下等,完全打破了静态资源只能放在 Web 容器的根路径下这个限制。

       b.<mvc:resources /> 依据当前著名的 Page Speed、YSlow 等浏览器优化原则对静态资源提供优化。

       SwaggerConfig 配置类:

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build();
        }
        private ApiInfo apiInfo() {
            ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
            apiInfoBuilder.title("SPM Doc");
            apiInfoBuilder.description("SPM Api文档");
            apiInfoBuilder.contact(new Contact("orson", "https://www.cnblogs.com/", ""));
            apiInfoBuilder.version("2.0");
            return apiInfoBuilder.build();
        }
    }

       对于生成哪些请求方法 API ? Swagger 提供了 RequestHandlerSelectors 对象的以下方法进行限制范围:

    2. 服务注解配置实践

       经过上述的操作,其实 Swagger 已经集成完毕,在项目开发推进中,只需在对应 RESTful 服务上添加对应注解即可。

      @Api:注解在类上,说明该类的作用。可以标记一个 Controller 类做为 swagger  文档资源,使用方式:

    @Api(description = "用户管理")

       @ApiOperation:注解在方法上,说明方法的作用,每一个url资源的定义,使用方式:

    @ApiOperation(value = "获取所有用户列表")

       @ApiParam、@ApiImplicitParam:注解到参数上,说明该参数作用,使用方式:

    @ApiParam(value = "用户ID") String userId

       上述都为最简配置,构建清晰的 API  文档已足够,当然还有很丰富的注解,知道有就行了。

    @RestController
    @Api(description = "用户管理")
    public class UserRestController extends BaseController {
        @Autowired
        private SysUserService sysUserService;
    
        @GetMapping("r/user/get")
        @ApiOperation(value = "获取特定用户详情")
        public Object getUser(ModelMap modelMap, @ApiParam(value = "用户ID") String userId) {
    
        }
    
        @PostMapping("r/user/add")
        @ApiOperation(value = "添加用户")
        public Object addUser(ModelMap modelMap, @ModelAttribute @Valid SysUser user, BindingResult result) {
    
        }
    }

       在项目后续使用中遇到的一些问题:

    a. 一些方法入参如 HttpServletRequest、HttpServletResponse、HttpSession、ModelMap 等等,这些参数在生成 API 文档时是无意义的,Swagger 正确的配置方式?

       刚开始时使用 @ApiParam(hidden = true)  注解这些参数,方法繁多的时候,这些类型的入参都要写一遍,使用起来很冗余。

       在 API 中发现 Docket 对象有 ignoredParameterTypes 方法,在配置类中统一定义忽略的参数类型即可,这样就方便很多。

    public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .ignoredParameterTypes(ModelMap.class, HttpServletRequest.class,HttpServletResponse.class, BindingResult.class)
                    .select()
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build();
        }

    b. 当请求的参数为封装的对象时,怎样进行注解?对象中的属性怎样注解?怎样屏蔽对象中的莫个属性?

       请求的参数为对象时,使用Spring @ModelAttribute 注解对应对象,对象当中的属性使用 @ApiModelProperty ,屏蔽莫个属性 @ApiModelProperty(hidden = true)

        @ApiModelProperty(hidden = true)
        private String uuid;
    
        @ApiModelProperty("姓名")
        private String name;
    
        @ApiModelProperty("密码")
        private String passwd;

    c. @Api 注解中的 tags 值不支持中文,中文值会导致无法展开;

       Swagger 有很丰富的工具,还能做很多事,本文所述只是能让你迅速了解它、使用它、有需要多查资料、多翻博客。

     

  • 相关阅读:
    Web CI/CD Continuous Integration / Continuous Delivery / Continuous Deployment
    hd + TP-Link Switch / wanzhaojiaohuanji / spf+ / TL-ST1008F / TL-ST5016F
    彻底理解js中this的指向,不必硬背(转)
    H5本地存储(转)
    jquery获得 当前页面url的变量
    js中实现base64加密、解密
    项目中easyui-tooltip提示消息运用
    Jquery生成二维码(微信中长按图片识别二维码功能)
    [hdu 3068] Manacher算法O(n)最长回文子串
    Hello world !
  • 原文地址:https://www.cnblogs.com/java-class/p/7544610.html
Copyright © 2011-2022 走看看