springboot 集成swagger2

Posted 2022-10-30 kingsonfu

使用Swagger 可以动态生成Api接口文档，在项目开发过程中可以帮助前端开发同事减少和后端同事的沟通成本，而是直接参照生成的API接口文档进行开发，提高了开发效率。这里以springboot(版本2.1.4.RELEASE)集成swagger2并以简单测试用例延时集成效果。

1、准备工作

pom依赖加入swagger

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

配置文件application.properties可以添加swagger.enabled配置控制是否开启

# 控制开启或关闭swagger
swagger.enabled=true

添加swagger配置类，主要用于配置生成api的相关信息

@Configuration
@EnableSwagger2
public class SwaggerConfig 


    /**
     * 控制开启或关闭swagger
     */
    @Value("$swagger.enabled")
    private boolean swaggerEnabled;
 
    @Bean
    public Docket createRestApi() 
        return new Docket(DocumentationType.SWAGGER_2)
                // api基础信息
                .apiInfo(apiInfo())
                // 控制开启或关闭swagger
                .enable(swaggerEnabled)
                // 选择那些路径和api会生成document
                .select()
                // 扫描展示api的路径包
                .apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger.controller"))
                // 对所有路径进行监控
                .paths(PathSelectors.any())
                // 构建
                .build();
    

    /**
     * @descripiton:
     * @author: kinson
     * @date: 2019/9/10 23:33
     * @param
     * @exception：
     * @modifier：
     * @return：springfox.documentation.service.ApiInfo
     */
    private ApiInfo apiInfo() 
        return new ApiInfoBuilder()
                // api名称
                .title("SwaggerUI APIS")
                // api 描述
                .description("Simple Demo About SwaggerUI APIS")
                // api 版本
                .version("1.0")
                // 构建
                .build();
    

这里的@EnableSwagger2用于让激活swagger，也可以加载启动类上。

添加测试url

@RestController
@Api(tags = "测试demo")
@RequestMapping(value = "swagger")
public class SwaggerController 

    @ApiOperation(value = "hello", notes = "hello测试api")
    @GetMapping(value = "hello")
    public String hello() 
        return "hello";
    

    @ApiOperation(value = "add", notes = "路径变量测试")
    @ApiImplicitParam(name = "swaggerId",value = "测试参数id",required = true, dataType = "Integer", paramType="path")
    @PostMapping(value = "add/swaggerId")
    public String add(@PathVariable Integer swaggerId) 
        Assert.notNull(swaggerId, "swaggerId为空");
        return swaggerId.toString();
    

    @ApiOperation(value = "update",notes = "多路径参数变量测试")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "swaggerId",value = "测试参数id",required = true, dataType = "Integer", paramType="path"),
            @ApiImplicitParam(name = "name",value = "测试参数名称",required = true, dataType = "String", paramType="path"))
    @PutMapping(value = "/update/swaggerId/name")
    public String update(@PathVariable Integer swaggerId,@PathVariable String name) 
        return String.valueOf(swaggerId + name);
    

    @ApiOperation(value = "addUser",notes = "对象添加测试")
    @ApiImplicitParam(name = "user",value = "待添加用户信息",required = true, dataType = "User", paramType="body")
    @ApiResponse(code = 200, message = "添加成功")
    @PostMapping(value = "/addUser")
    public String addUser(@RequestBody User user)

        return user.getName();
    

上述工作加完后就可以启动项目查看效果，打开浏览器访问http://127.0.0.1:8080/swagger-ui.html，如下图则表示集成成功

 2、swagger 相关注解

• @Api：用在类上，标志此类是Swagger资源 value：接口说明 tags：接口说明，可以在页面中显示。可以配置多个，当配置多个的时候，在页面中会显示多个接口的信息
• @ApiOperation：用在方法上，描述方法的作用
• @ApiImplicitParams：包装器，包含多个ApiImplicitParam对象列表
• @ApiImplicitParam：定义在@ApiImplicitParams注解中，定义单个参数详细信息，如下：　　

　　　　○ paramType：参数放在哪个地方
　　　　　　§ header-->请求参数的获取：@RequestHeader
　　　　　　§ query-->请求参数的获取：@RequestParam
　　　　　　§ path（用于restful接口）-->请求参数的获取：@PathVariable
　　　　　　§ body（以流的形式提交 仅支持POST）
　　　　　　§ form（以form表单的形式提交 仅支持POST）
　　　　○ name：参数名
　　　　○ dataType：参数的数据类型 只作为标志说明，并没有实际验证
　　　　　　§ Long
　　　　　　§ String
　　　　○ required：参数是否必须传
　　　　　　§ true
　　　　　　§ false
　　　　○ value：参数的意义
　　　　○ defaultValue：参数的默认值

• @ApiModel：描述一个Swagger Model的额外信息
• @ApiModel用在类上，表示对类进行说明，用于实体类中的参数接收说明
• @ApiModelProperty：在model类的属性添加属性说明
• @ApiParam：用于Controller中方法的参数说明
• @ApiResponses：包装器：包含多个ApiResponse对象列表
• @ApiResponse：定义在@ApiResponses注解中，一般用于描述一个错误的响应信息 。如下：
  • code：错误码，例如400
  • message：信息，例如"请求参数没填好"
  • response：抛出异常的类
• @Authorization 声明要在资源或操作上使用的授权方案。
• @AuthorizationScope 描述OAuth2授权范围

 

Github源码参照