Spring Boot学习：如何使用Swagger文档构建自己的API文档

Swagger

随着前后端分离架构和微服务架构的流行，我们使用Spring Boot来构建RESTful API项目的场景越来越多，在多人协作的团队中，前后端的沟通成本往往比较大。在这样的背景下，Swagger出现了(当然还有其他的就不一一例举了)。

使用 Swagger 集成文档具有以下几个优势：

• 功能丰富 ：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能
• 及时更新 ：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力
• 整合简单 ：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务

开始整合Swagger2

在上一篇的项目基础上，我们来使用一下Swagger。

1. 首先，我们需要在pom.xml中添加依赖,如下:

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

2. 接下来我们来编写一个SwaggerConfig配置类
   新建一个包:com.zhlab.demo.config,创建SwaggerConfig类
   SwaggerConfig.java

package com.zhlab.demo.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;

/**
 * @ClassName SwaggerConfig
 * @Description //SwaggerConfig配置类
 * @Author singleZhang
 * @Email [email protected]
 * @Date 2020/10/17 0017 上午 11:11
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {


    @Bean
    public Docket creatRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.apiInfo())
                .select()
                //扫描指定路径
                .apis(RequestHandlerSelectors.basePackage("com.zhlab.demo.controller"))
                // 扫描所有有注解的api，用这种方式更灵活
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描所有
                // .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("zhLab Demo Api Doc")
                .description("api document of zhLab Demo")
                .version("1.0.1")
                .build();
    }

}

※说明:

• 在类上，添加 @EnableSwagger2 注解， 标记项目启用 Swagger API 接口文档。
• 通过 createRestApi() 方法，创建 Swagger Docket Bean
• 更多的配置可以在Docket.java、ApiInfo.java两个类的源码中查看

3. 修改上一篇中的HelloController控制器

package com.zhlab.demo.controller;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

/**
 * @ClassName HelloController
 * @Description //第一个Springboot接口
 * @Author singleZhang
 * @Email [email protected]
 * @Date 2020/10/16 0016 上午 10:55
 **/
@RestController
@RequestMapping("/system/user")
public class HelloController {

    /* 方法注解 */
    @ApiOperation(value = "方法名:打招呼", notes = "打招呼方法的测试")
    @GetMapping("/hello")
    public String sayHello(/* 参数注解 */ @ApiParam(value = "参数:名字" , required=true ) @RequestParam String name){
        return "hi"+name+" ,I can say hello";
    }
}

启动项目,在浏览器输入http://localhost:8080/swagger-ui.html显示下图:

swagger-ui

执行一下，测试一下接口:

TEST

常用注解说明

swagger 通过注解接口生成文档，包括接口名，请求方法，参数，返回信息等。
@Api: 修饰整个类，用于controller类上
@ApiOperation: 描述一个接口，用户controller方法上
@ApiParam: 单个参数描述
@ApiModel: 用来对象接收参数,即返回对象
@ApiModelProperty: 对象接收参数时，描述对象的字段
@ApiResponse: Http响应其中的描述，在ApiResonse中
@ApiResponses: Http响应所有的描述，用在
@ApiIgnore: 忽略这个API
@ApiError: 发生错误的返回信息
@ApiImplicitParam: 一个请求参数
@ApiImplicitParam: 多个请求参数

总结

以上就是对Swagger的初步体验,前后端分离api文档是节省沟通成本的重要工具，用好它，你肯定会如虎添翼，以后还会推荐YAPI等工具。

项目地址

https://gitee.com/kaixinshow/springboot-note

返回【Spring Boot学习】目录