spring boot项目利用swagger生成api文档

零、前言

    接口文档在项目开发中是非常重要的，是前后端协同开发的有力武器，如果没有一个良好  的接口文档来给相关开发人员查看接口的情况（或者变化），那么前后端的开发工作耦合程度（指的是需要经常询问接口情况）将会严重增加。

一、swagger简介

    Swagger是一款Restful接口的文档在线自动生成和功能测试功能软件。
    
    Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

swagger优缺点

优点

• 节省了大量手写接口文档的时间

• 通过注解自动生成在线文档

• 接口在线调用调试

缺点

• 代码耦合，需要注解支持

• 代码侵入性比较强

• 无法测试错误的请求方式、参数及不限于这些

自己写文档的缺点

• 文档更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时

• 接口返回结果不明确

• 不能直接在线测试接口，通常需要使用工具，比如postman

• 接口文档太多，不好管理

二、SpringBoot 中使用swagger步骤

pom.xml

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.0</version>
</dependency>

Swagger配置类

package com.springswagger.config;

import org.springframework.beans.factory.annotation.Value;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Description
 * @ClassName SwaggerConfig
 * @Author User
 * @date 2020.06.11 22:15
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // swagger开关，开发环境开启，生产环境关闭
    @Value("${swagger.enabled}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                .enable(enableSwagger)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com.springswagger.controller"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * @Description swagger基本信息
     * @Param
     * @return 
     * @Author zhen.ma
     * @Date 2020.06.11 22:26
     **/
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot使用Swagger2构建restful Api文档")
                //文档描述
                .description("接口说明")
                //服务条款URL
                .termsOfServiceUrl("http://127.0.0.1:8080/")
                //联系信息
                .contact(new Contact("san.zhang","http://san.zhang.com","[email protected]"))
                //版本号
                .version("V1.0")
                .build();
    }
}

解释：
@Configuration标注在类上，相当于把该类作为spring的xml配置文件中的，作用为：配置spring容器(应用上下文)。用@Bean标注方法等价于XML中配置bean。

@EnableSwagger2的作用是启用Swagger2相关功能。

Docket对象包含三个方面信息：

• 整个API的描述信息，即ApiInfo对象包括的信息，这部分信息会在页面上展示。

• 指定生成API文档的包名。

• 指定生成API的路径。

controller类

只是为了说明swagger的用法，我们只写了controller类，如下：

package com.springswagger.controller;

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

import java.util.HashMap;
import java.util.Map;

/**
 * @Description
 * @ClassName MySwaggerController
 * @Author User
 * @date 2020.06.11 22:14
 */
@RestController
@RequestMapping("api/v1")
@Api(value = "测试接口", tags = "UserController", description = "测试接口相关")
public class MyController {

    @GetMapping("/")
    @ApiOperation(value = "访问网站首页", notes = "网站首页")
    public void index() {

    }

    @GetMapping(value = "/mi", produces = "application/json")
    @ApiImplicitParam(name = "num", value = "数字", required = true, dataType = "int", paramType = "query")
    @ApiOperation(value = "一个数的平方", notes = "求一个数的平方")
    public int getNum2(@RequestParam int num) {
        return num*num;
    }
}

api文档访问

http://localhost:8080/swagger-ui.html

   当然，这个接口文档非常不完善，只有一个get请求的接口说明，而且不详细，后续将会补充完中。

    这样，就完成了在springboot中使用swagger文档的功能，是不是也不复杂呢，相比于nodejs中在swagger中编写yaml文件，可以说更加直观。

三、文档注解说明

注解说明

常用注解说明：

@Api：用于controller类上，说明该类的作用

• tags=“说明该类的作用，可以在UI界面上看到的注解”

• value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”

@ApiOperation：用在controller的方法上，用来说明方法用途、作用

• value=“说明方法的用途、作用”

• notes=“方法的备注说明”

@ApiImplicitParam：用来给方法入参增加说明

• name：参数名

• value：参数的汉字说明、解释

• dataType： 参数类型，默认String

• required ： 参数是否必传，true必传

• defaultValue：参数的默认值

• paramType：参数放在哪个地方

• header请求参数的获取:@RequestHeader,参数从请求头获取

• query请求参数的获取:@RequestParam,参数从地址栏问号后面的参数获取

• path（用于restful接口）请求参数的获取：@PathVariable，参数从URL地址上获取

• body（不常用）参数从请求体中获取

• form（不常用）参数从form表单中获取

@ApiImplicitParams：用在controller的方法上，一组@ApiImplicitParam

@ApiResponse：用在 @ApiResponses里边，一般用于表达一个错误的响应信息

• code：数字，例如400

• message：信息，例如"请求参数没填好"

• response：抛出异常的类

@ApiResponses：用在controller的方法上，用于表示一组响应

@ApiModel：用在返回对象类上，描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty：用在出入参数对象的字段上，表示对model属性的说明或者数据操作更改

• value = 字段说明
• name = 重写属性名字
• dataType = 重写属性类型
• required = 是否必填，true必填
• example = 举例说明
• hidden = 隐藏

@ApiIgnore：使用该注解忽略这个API，不会生成接口文档。可注解在类和方法上

四、总结

   本文简答记录了下springboot中使用swagger生成接口文档的基本方法，后续需要继续完善，继续学习实践。

五、demo地址

   [github](https://github.com/SUST-MaZhen/spring-swagger.git)