Springboot项目整合swagger2在线API文档

我会带着你远行 2022-04-01 12:46 348阅读 0赞

由于Spring Boot能够快速开发、便捷部署等特性，相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因，这些终端会共用很多底层业务逻辑，因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。

这样一来，我们的RESTful API就有可能要面对多个开发人员或多个开发团队：IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本，传统做法我们会创建一份RESTful API文档来记录所有接口细节，然而这样的做法有以下几个问题：

*  由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。
 *  随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致不一致现象。

为了解决上面这样的问题，本文将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0RyZWFtX3h1bg_size_16_color_FFFFFF_t_70][]

### 整合过程 ###

**添加swagger2依赖**

<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>

**创建swagger配置类**

/**
     * Swaggers 配置
     */
    @Configuration
    //启用swagger,生产环境请注释掉
    @EnableSwagger2
    public class Swaggers {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enableUrlTemplating(true)
                    .select()
                    // 扫描所有有注解的api，用这种方式更灵活
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        /**
         * 首页描述
         * @return
         */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Spring Boot中使用Swagger2构建RESTful APIs")
                    .description("更多Spring Boot相关文章请百度：http://www.baidu.com")
                    .termsOfServiceUrl("http://www.baidu.com/")
                    .build();
        }
    }

@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解启用Swagger2

**在线文档添加**

@RestController
    @RequestMapping(value = "/users")
    @Api(value = "用户测试信息", tags = {"用户测试相关接口"})//swagger控制器说明注解
    public class UserController {
         /**
         * * 入参是对象,使用默认参数paramType = "body"
         * ApiIgnore()用于类，方法，方法参数
         * 表示这个方法或者类被忽略,不被显示在swagger页面上
         * @param resp
         * @param id
         * @param user
         * @return
         */
        @ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
        })
        @RequestMapping(value = "/{id}", method = RequestMethod.PUT)
        public String putUser(@ApiIgnore ApiReturnInfo resp,@PathVariable Long id, @RequestBody User user) {
            User u = users.get(id);
            u.setName(user.getName());
            u.setAge(user.getAge());
            users.put(id, u);
            return "success";
        }
    
    }

### 添加swagger注解之后，启动springboot服务，访问浏览器[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html] 就可以看到在线的API文档。 ###

**waggerUI访问404解决**   
重新指定静态资源，把swagger-ui.html页面加入

@Configuration
    public class ServletContextConfig extends WebMvcConfigurationSupport {
        /**
         * 重新指定静态资源
         * @param registry
         */
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/**")
                    .addResourceLocations("classpath:/static/");
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
            super.addResourceHandlers(registry);
        }
    
    }

### 使用体会 ###

感觉在线文档生成倒是很好用，但swagger自带的接口测试不怎么好用，需要注意很多，   
1、在接收参数的地方需要使用@RequestBody，才能接收，这点需要注意下；使用过springboot的同学都清楚，接收参数不需要加注解，就能接收。   
2、如果存在多个参数类型，自定义对象及基础类型，这种数据即使使用@RequestBody，后台也是接收失败。目前还没找到解决方案，暂时只使用swagger2的在线文档，调试还是使用postman，汗颜…. ps:有解决方案的小伙伴请留言，不胜感激   
完整demo请参考:springboot-swagger2-demo

swagger常用注解说明

@Api()用于类；   
表示标识这个类是swagger的资源  
@ApiOperation()用于方法；   
表示一个http请求的操作  
@ApiParam()用于方法，参数，字段说明；   
表示对参数的添加元数据（说明或是否必填等）  
@ApiModel()用于类   
表示对类进行说明，用于参数用实体类接收  
@ApiModelProperty()用于方法，字段   
表示对model属性的说明或者数据操作更改  
@ApiIgnore()用于类，方法，方法参数   
表示这个方法或者类被忽略  
@ApiImplicitParam() 用于方法   
表示单独的请求参数  
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam  
\---------------------   
原文：https://blog.csdn.net/chunzhilianxue/article/details/79835521

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L0RyZWFtX3h1bg_size_16_color_FFFFFF_t_70]: /images/20220401/08de811a3e2444eca1230e2d77527f75.png
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html