Swagger2 的简单应用

Swagger2

Swagger2简介
1. 整合 Spring Boot
2. 创建 Swagger 2 的配置类
3. 创建 controller 的接口

User 实体类代码如下：

4. 启动项目，进行测试
结语

Swagger2简介

通常在前后端开发中，为了减少一些沟通成本，一般都会构建一份 RESTful API 文档来描述所有的接口信息
Swagger 2 是一个开源软件框架，可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务，它将代码和文档融为一体，

1. 整合 Spring Boot

首先创建 Spring Boot Web 项目，添加 Swagger 2 的相关依赖，代码如下：

		<dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

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

2. 创建 Swagger 2 的配置类

首先通过@EnableSwagger2注解开启 Swagger2
然后在通过 apis 这个方法配置要扫描的 controller 位置，通过 paths 方法配置路径
在 apiInfo 中构建文档的基本信息，比如描述、联系人信息、版本、标题等等

@Configuration
@EnableSwagger2 //此注解表示开启 Swagger 2
public class SwaggerConfig {
    @Bean
    Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sang.swagger2.controller"))   //配置 controller 的位置
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()   // 在 apiInfo 中构建文档的基本信息
                .description("员工管理接口测试文档")
                .contact(new Contact("小白哥",
                        "https://gitee.com/jian_bo_bai/dashboard/projects",
                        "[email protected]"))
                 .version("v1.0")
                 .title("API 测试文档")
                 .license("Apache2.0")
                 .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                 .build());
    }
}

3. 创建 controller 的接口

Swagger 2 配置完成后，接下来就创建 controller 接口测试，代码如下：

注解	作用
@Api	此注解用来描述整个 Controller 信息
@ApiOperation	此注解用在开发方法上，用来描述一个方法的基本信息，value是对方法作用的一个简短描述，notes 则用来备注该方法的详细作用
@ApiImplicitParam	此注解用在方法上，用来描述方法的参数，paramType 是指方法参数的类型，可选值有 path(参数获取方式 @PathVariable) query(参数获取方式 @RequestParam) header(参数获取方式 @RequestHeader) body 以及 form ; name 表示参数名称，value 是参数的描述信息，required 表示该字段是否必填，defaultValue 表示该字段的默认值
@ApiResponse	此注解是对相应结果的描述，code 表示响应码， message 表示对应的描述，若有多个 @ApiResponse 则可以放在一个 @ApiResponses 中
@ApiIgnore	此注解表示不对某个接口生成文档

@RestController
@Api(tags = "用户数据接口")   //此注解用来描述当前 controller 的信息
public class UserController {

    @ApiOperation(value = "查询用户",notes = "根据 id 查询用户")
    @ApiImplicitParam(paramType = "path",name = "id",value = "用户id",required = true)
    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable Integer id) {
        return "/user/" + id;
    }

    @ApiResponses({
            @ApiResponse(code = 200,message = "删除成功！"),
            @ApiResponse(code = 500,message = "删除失败！")})
    @ApiOperation(value = "删除用户",notes = "通过 id 删除用户")
    @DeleteMapping("/user/{id}")
    public Integer deleteUserById(@PathVariable Integer id) {
        return id;
    }

    @ApiOperation(value = "添加用户",notes = "添加一个用户，传入用户名和地址")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query",name = "username",value = "用户名",required = true,defaultValue = "sang"),
            @ApiImplicitParam(paramType = "query",name = "address",value = "用户地址",required = true,defaultValue = "shenzhen")})
    @PostMapping("/user")
    public String addUser(@RequestParam String username,@RequestParam String address) {
        return username + ":" + address;
    }

    @ApiOperation(value = "修改用户",notes = "修改用户，传入用户信息")
    @PutMapping("/user")
    public String updateUser(@RequestBody User user) {
        return user.toString();
    }

    @GetMapping("/ignore")
    @ApiIgnore
    public void ingoreMethod() {}
}

User 实体类代码如下：

@ApiModel(value = "用户实体类",description = "用户信息描述类")
public class User implements Serializable {
    @ApiModelProperty(value = "用户名")
    private String username;
    @ApiModelProperty(value = "用户地址")
    private String address;

    public User() {
        super();
    }

    public User(String username, String address) {
        this.username = username;
        this.address = address;
    }

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", address='" + address + '\'' +
                '}';
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }
}