Spring Boot 使用 Swager自动生成接口文档

@作者：jackieonway
链接：https://www.jianshu.com/p/49afc7465ce5
来源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

前言

工作中难免会遇到写文档，特别是在大型项目中，接口文档的编写一直是一个令人头疼的问题，开发人员会花费大量的时间去写接口文档。今天推荐一款自动生成接口的工具----Swagger ,它大大的节约了开发人员的写文档的时间，最重要的是，它还支持在线接口测试，Swagger官网为https://swagger.io/。

一、Swagger 常用注解

@Api()用于类；
表示标识这个类是swagger的资源
@ApiOperation()用于方法；
表示一个http请求的操作
@ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
@ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
@ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
@ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略
@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

二、如何使用Swagger？

（一） 开发工具

JDK1.8
Apache Maven 3.5.0
IntelliJ IDEA 2018.2.5

（二）引入依赖

<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>

（三）配置Swagger

package com.example.demo.swagger.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


/**
 * @Author: Jackieonway
 * @Description: Swagger 配置类
 * @Version: 1.0
 */

@EnableSwagger2
@Configuration
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //Controller所在包(必须新建包)
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.swagger.controller"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            //接口文档的名字
            .title("demo api")
            //接口文档的描述
            .description("demo api接口文档")
            //服务条款网址
            .termsOfServiceUrl("http://localhost/")
            //接口文档的版本
            .version("1.0.0")
            // 接口文档维护联系信息
            .contact(new Contact("Jakieonway", "", "jackieonway@outlook.com"))
            .build();
    }
}

（四） 使用Swagger
参数Model使用

package com.example.demo.swagger.entity;

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

/**
 * @author Jackieonwaya
 * @version 1.0
 **/
@ApiModel("示例实体")  //参数Model对应的接口文档
public class Demo {

    @ApiModelProperty("名字")  //参数Model对应属性的接口文档描述
    private String name;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @Override
    public String toString() {
        final StringBuilder sb = new StringBuilder("{");
        sb.append("\"name\":\"")
                .append(name).append('\"');
        sb.append("}");
        return sb.toString();
    }
}

测试Controller

package com.example.demo.swagger.controller;

import com.example.demo.swagger.entity.Demo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author Jackieonway
 * @version 1.0
 **/
// 用于类；表示标识这个类是swagger的资源
//tags:说明，如果有多个tags,则会以list形式展示
//value: 说明，可以使用tags替代
@Api(value = "测试Controller" , tags = "测试类")
@RestController
public class TestController {

    //用于方法；表示一个http请求的操作
    //value: 用于方法描述
    //notes: 用于提示内容
    //tags: 可以重新分组
    @ApiOperation(value = "测试方法")
    @GetMapping("/get")
    //用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等） 
    //name:参数名 
    //value:参数说明 
    //required:是否必填
    public String get(@ApiParam(name = "姓名",value = "姓名值",required = true) String name){
        return "Swagger 测试 返回值 : " + name;
    }

    @ApiOperation(value = "测试返回方法",notes = "必传参数: name")
    @GetMapping("/getDemo")
    public Demo getDemo(Demo demo){
        return demo;
    }
}

使用效果
访问 http://localhost:8080/swagger-ui.html
Swagger界面

以多个参数形式接收，如果设置@ApiParam 的required = true则会显示required

以对象接收

小结
通过以上的配置和使用，Swagger在Spring Boot中已经成功完成。接下来就看小伙伴在项目中的实际使用吧。更多关于Swagger的用法，请参考官方使用文档。

附完整的Pom文件

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>demo-swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>demo-swagger</name>
    <description>Demo project for Spring Boot</description>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.0.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    <!-- Swagger 配置开始  -->
        <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>
  <!-- Swagger 配置结束  -->

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>


</project>