Spring Boot 2：Swagger 2

Swagger 简介

解决的问题

互联网技术发展，网站架构从原来的后端渲染 => 前后端分离。前端技术和后端技术各自的发展中，两者唯一的联系就是API接口，所以API 文档变成了前后端开发人员联系的纽带，变得越来越重要。

但是随着代码的不断更新，开发人员对接口的 开发/维护 往往会没有即使同步到API文档中，很容易影响后续的开发工作。

Swagger 就是用来解决该问题的一款重要的工具。
开发人员不再需要提供文档，只要提供 Swagger 地址，即可展示在线的 API 接口文档。并且，调用接口的人员还可以在线测试接口数据，包括开发人员在开发接口时，同样也可以利用 Swagger 在线接口文档测试接口数据！

Swagger 官方的定位

 

Swagger构建Restful API

 

 <properties>
        <swagger2.version>2.2.2</swagger2.version>
 </properties>

        <!--swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger2.version}</version>
        </dependency>

@Configuration
// 开启swagger2
@EnableSwagger2
public class SwaggerConfig {

    /*
    通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该API的基本信息
    （这些基本信息会展现在文档页面中）。
    select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，
    本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，
    并产生文档内容（除了被@ApiIgnore指定的请求）。

    通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明
     */

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("sun.flower.yang.web.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("宜修のRESTful APIs")
                .description("My Restful APIs")
                // 设置联系方式
                .contact("yangxuyue，" + "鱼点困")
                .termsOfServiceUrl("http://www.sunflower.com/yang21/")
                .version("1.0")
                .build();
    }

}

 localhost:8080/swagger-ui.html

 

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "用户实体类")
public class User {

    @ApiModelProperty(value = "用户唯一标识")
    private Long id;

    @ApiModelProperty(value = "用户姓名")
    private String username;

    @ApiModelProperty(value = "用户密码")
    private String password;
}

 

@Api(value = "用户管理", description = "User Manage")
@RestController
public class UserController {

    @ApiOperation(value = "获取一个用户", notes = "根据用户id获取")
    @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")
    @GetMapping("/users/{id}")
    public ResultBean getUser(@PathVariable("id") Long id) {
        return ResultBean.ok();
    }

    @ApiOperation("更新一个用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    @PutMapping("/users/{id}")
    public ResultBean updateUser(@PathVariable("id") Long id,
                                 @RequestBody String user) {
        return ResultBean.ok();
    }
}

更多注解信息

@Api： 描述Controller
@ApiIgnore： 忽略该Controller，指不对当前类做扫描
@ApiOperation： 描述Controller中的method接口
@ApiParam： 单个参数描述，在入参上使用
@ApiModel： 描述POJO对象
@ApiProperty： 描述POJO对象中的属性值
@ApiImplicitParam： 描述单个入参信息
@ApiImplicitParams： 描述多个入参信息
@ApiResponse： 描述单个出参信息
@ApiResponses： 描述多个出参信息
@ApiError： 接口错误所返回的信息