Swagger2:

减少与其他团队的沟通成本，构建RESTFUL API文档来描述所有的接口信息

• 接口众多，编写RESTFUL API文档工作量大。文档包含接口的基本信息和HTTP请求类型、HTTP请求头、请求参数类型、返回值类型、所需权限
• 维护不方便，接口变化则需要修改文档
• 接口测试不方便，需要postman等工具

Swagger2是一个开源的软件框架，帮助设计、构建、记录、使用RESTful web服务，将代码和文档融合。解决上面的问题。

SpringBoot整合 Swagger2：

1.添加依赖:

        <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>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

2.创建Swagger配置类：

package com.yinlei.swigger2;

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yinlei.swigger2"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                .description("测试文档")
                .contact(new Contact("尹磊","http://www.yinleilei.com","[email protected]"))
                .version("v1.0")
                .title("API测试文档")
                .license("Apache2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build());
    }
}

通过@EnableSwagger2开启Swagger2，主要配置是一个Docket

通过apis()配置扫描的controller位置，

通过paths方法去配置路径

在apiinfo中构建文档的基本信息等

3.开发接口:

• @Api用在类上，描述整个Controller信息
• @ApiOperation用在开发方法上，描述一个方法的基本信息，value是对方法作用的简短描述，notes是备注该方法的详细作用
• @ApiImplicitParam用在方法上，描述方法的参数，paramType是参数的类型，可选值有(path(@PathVariable),query(@RequestParam),header(@RequestHeader),body和form)。name是参数名，和参数变量对应。value是参数的描述信息，required表示该字段是否必填，defaultValue是默认值。defaultValue，required只是文档上的约束描述，不是真正约束接口。如果方法有多个参数，可将多个参数的@ApiImplicitParam放到@ApiImplicitParams中。
• @ApiResponse是对响应结果的描述，code是响应码，message是相应描述信息
• @ApiModel和@ApiModelProperty配置实体类对象的描述信息
• @ApiIgnore是对某个接口不生成文档。

package com.yinlei.swigger2;

import io.swagger.annotations.*;
import lombok.Getter;
import lombok.Setter;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@Api(tags = "用户数据接口")
public class UserController {
    @ApiOperation(value = "查询用户",notes = "根据id查询")
    @ApiImplicitParam(paramType = "path",name = "id")
    @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 = "yinlei"),
            @ApiImplicitParam(paramType = "query",name = "address",value = "用户地址",required = true,defaultValue = "绵阳")
    })
    @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 ignoreMethd(){

    }

}

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

对接口进行测试：

都可以不用postman等工具了。 

下文：SpringBoot企业开发: 数据校验