「快学springboot」16.让swagger帮忙写接口文档

swagger简介

官方的介绍

THE WORLD'S MOST POPULAR API TOOLING
Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS),
enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

这段话首先告诉大家Swagger是世界上最流行的API工具，并且Swagger的目的是支撑整个API生命周期的开发，包括设计、文档以及测试和部署。使用swagger，可以节省写接口文档的时间，同时也方便对接口进行测试。下面讲解在springboot如何整合swagger。

引入依赖

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

配置

新建Swagger2Config.class

/**
 * @author Happy
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createAdminApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("api")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.happyjava.springboot"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("系统接口")
                .description("测试系统接口")
                .version("1.0")
                .build();
    }
}

这里配置了swagger的基本信息，可以根据具体需要，自定义修改。

效果

把以上两个步骤做完之后，已经可以看到swagger的效果了。打开http://127.0.0.1:8080/swagger-ui.html，效果如下：

这些都是之前写的一些接口

使用swagger调试接口

现在有以下三个类ResultVO.class，SwaggerTestController.class，TestParam.class如下：

@Data
public class ResultVO {

    private String result;

    private String message;

}

@RestController
@RequestMapping(value = "/api/swagger")
public class SwaggerTestController {

    @PostMapping
    public ResultVO test(TestParam param) {
        return new ResultVO();
    }

}

@Data
public class TestParam {

    private String username;

}

重启应用，查看效果：

可以看到，接口的请求参数和响应参数，都自动的在swagger文档上列出来了。

点击Try it out，会弹出输入框，我们可以在此输入测试的参数，如下：

输完参数后，点击执行：

这里可以获得响应的结果。

字段描述

虽然这里swagger已经自动帮我们构建了接口文档了，但是却缺少字段的描述，会让前后端合作其实不是那么舒畅。swagger是可以通过注解的形式，为字段添加描述属性的。

实体参数描述

当使用@RequestBody的形式来接口参数时，可以使用ApiModel来标识类，使用ApiModelProperty来标识属性。修改TestParam.class如下：

@Data
@ApiModel(value = "测试参数")
public class TestParam {

    @ApiModelProperty(value = "用户名", required = true)
    private String username;

}

重启应用，查看效果：

点击Model，可以查看到字段的描述。

字段参数描述

如果我们采用queryString的形式来接受参数，又或者是get请求，这时候@ApiParam注解来描述字段。修改SwaggerTestController，添加如下方法：

    @GetMapping
    public ResultVO get(@ApiParam(value = "请求id") String requestId) {
        return new ResultVO();
    }

重启应用查看效果：

响应参数描述

我们也需要对响应的字段进行描述，其实跟实体参数描述里的用法是一致的。修改ResultVO.class如下：

@Data
@ApiModel(value = "响应")
public class ResultVO {

    @ApiModelProperty(value = "这是结果")
    private String result;

    @ApiModelProperty(value = "这是信息")
    private String message;

}

重启应用查看效果：

总结

这里讲解了springboot继承swagger，以及使用swagger的注解来描述参数和响应的字段。swagger在描述字段的时候，还有很丰富的用法，具体的api读者可以在需要时查看api文档即可。