SpringBoot Swagger2 快速上手

小灰灰 2022-05-21 03:15 156阅读 0赞

曾经我们使用的接口文档，都是基于word格式，缺点太明显。文档每次更新需要手动发送给前端开发者，更新交流不及时、不能在线直接测试，可能存在多个模块的文档，不便管理。写接口文档描述也花时间，前端开发者看着文档也累、、、

so，我们team自己开发了一套接口文档插件，基于注解形式自动生成html文档。哇，不用写文档了，真tm开心，哈哈。

直到某年某月的某一天，发现了swagger这样的神器。比我们做的更大而全，也是开源项目，懒人开发的福音。

直接开始！pom中引入依赖：

<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配置类：

package org.jc.demo.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    
    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;
    /**
     * Swagger 配置类<br/>
     * Author:杨杰超<br/>
     * Date:2018年6月18日 下午11:26:51 <br/>
     * Copyright (c) 2018, yangjiechao@dingtalk.com All Rights Reserved.<br/> 
     *
     */
    @Configuration
    @EnableSwagger2
    public class Swagger2 {
    
        @Bean
        public Docket createRestApi() {
            // 创建API基本信息
            return new Docket(DocumentationType.SWAGGER_2)
                    // 选择那些路径和api会生成document
                    .apiInfo(apiInfo()).select()
                    // 扫描该包下的所有需要在Swagger中展示的API，@ApiIgnore注解标注的除外
                    .apis(RequestHandlerSelectors.basePackage("org.jc.demo.controller"))
                     对所有api进行监控
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            // 创建API的基本信息，这些信息会在Swagger UI中进行显示
            return new ApiInfoBuilder()
                    // API标题
                    .title("测试文档神器Swagger APIs")
                    // API描述
                    .description("这里是描述信息")
                    // 版本号
                    .version("1.0").build();
        }
    
    }

Docket、ApiInfoBuilder对象具体参数请查阅源码与相关资料，这里只提供最简单的实现。

然后添加Controller

@RestController
    @Api(tags = "grab-service", description = "抓取服务相关接口")
    public class TestController {
        @Autowired
        private TestService service;
    
        // 使用该注解描述接口方法信息
        @ApiOperation(value = "接口名称", notes = "接口的描述信息") 
        @ApiImplicitParams(
                {@ApiImplicitParam(name = "name", value = "名称", required = true, dataType = "String", paramType = "path")}
                )
        @RequestMapping(value = "/test/{name}", method = RequestMethod.GET)
        public String test(@PathVariable String name) {
            return service.test(name);
        }

**常用注解：**   
@Api()用于类；                                             表示标识这个类是swagger的资源   
@ApiOperation()用于方法；                         表示一个http请求的操作   
@ApiParam()用于方法，参数，字段说明；    表示对参数的添加元数据（说明或是否必填等）   
@ApiModel()用于类                                      表示对类进行说明，用于参数用实体类接收   
@ApiModelProperty()用于方法，字段           表示对model属性的说明或者数据操作更改   
@ApiIgnore()用于类，方法，方法参数           表示这个方法或者类被忽略   
@ApiImplicitParam() 用于方法                      表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

权威指南：[github项目主页][github]

就这样就可以在项目中直接使用Swagger生成接口文档了，

启动项目，直接访问:http://localhost:port/swagger-ui.html 查看效果吧。

我们在项目中很少这样用，感觉需要设置的东西太多了，精简了一些参数。效果如下：

@RestController
    @RequestMapping(value = "/order", produces = "application/json")
    @Api(description = "订单服务接口", tags = "api-order")
    public class OrderController extends AbstractController {
    
        @Autowired
        private OrderService orderService;
    
    
        @ApiOperation(value = "订单支付", notes = "订单支付")
        @ApiResponses({
                @ApiResponse(code = 601, message = "请求参数错误"),
                @ApiResponse(code = 602, message = "系统未知异常")
                //
        })
        @RequestMapping(value = "/order/pay", method = {RequestMethod.POST})
        public BaseRespDto orderPay(@RequestBody OrderPayReqDto req) {
            return orderService.orderPay(req);
        }
    }

参数详细注解在参数类中实现

BaseRespDto：

import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    public class BaseRespDto {
        
        @ApiModelProperty(notes = "结果描述")
        private String respMsg = "成功";
    }

OrderPayReqDto：

import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    @ApiModel("订单支付请求实体")
    public class OrderPayReqDto extends BaseReqDto {
    
        @ApiModelProperty(notes = "订单ID")
        private Long orderId;
        // 省略其他参数
    }

Swagger2 GitHub ： [https://github.com/swagger-api/swagger-core][https_github.com_swagger-api_swagger-core]

[github]: https://github.com/swagger-api/swagger-core/wiki/Annotations
[https_github.com_swagger-api_swagger-core]: https://github.com/swagger-api/swagger-core