Springboot整合接口文档工具Swagger2

什么是Swagger

• OpenAPI规范, 试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程
• Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发

Springboot中整合Swagger2

• 添加Swagger2依赖共2个

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

• 在项目中新增Swagger2配置类

package com.test.swagger.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;

/**
 * Swagger2配置类
 */
@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //指定了包路径com.test.swagger.controller，找到在此包下及子包下标记有@RestController注解的controller类并根据注解生成文档
                .apis(RequestHandlerSelectors.basePackage("com.test.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("测试api文档")
                // 文档描述
                .description("测试api文档描述.....")
//                .termsOfServiceUrl("/")
                // 文档版本号
                .version("1.0")
                .build();
    }
}

• 编写接口控制器
  实体类

package com.test.swagger.domain;

public class User {
    private String name;
    private Integer age;
    // getter setter方法省略.....
}

控制器

package com.test.swagger.controller;

import com.test.swagger.domain.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

// 控制器接口文档描述
@Api(description = "用户接口")
@RestController
@RequestMapping("/user")
public class UserController {
    
    // 当前接口描述
    @ApiOperation(value = "新增用户", notes = "添加一个新用户到数据库")
    @PostMapping(value = "/createUser")
    public void createUser(@RequestBody User user){
        System.out.println(user.toString());
    }
}

到这里, Swagger2就已经成功集成到我们的Springboot项目中了

测试一下

访问: http://localhost:8080/swagger-ui.html

image.png

最后再补充下Swagger2的常用注解
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对 象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用 该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数