Springboot整个Swagger2，构建Api文档

手写Api文档的几个痛点：

1 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
2 接口返回结果不明确
3 不能直接在线测试接口，通常需要使用工具，比如postman
4 接口文档太多，不好管理

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

其他的不多说，想要了解Swagger的，可以去Swagger官网，可以直接使用Swagger editor编写接口文档，当然我们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。
一 依赖

  <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>


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

二 Swagger2配置类

package com.kyrie.mybatis.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;

/**
 * @Author: txma
 * @Date: 2019/3/31 21:50
 * @Version: 1.0
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket CreateRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kyrie.mybatis.controller"))
                .paths(PathSelectors.any())
                .build();

    }

  private ApiInfo apiInfo() {
      return new ApiInfoBuilder()
              .title("Spring Boot中使用Swagger2构建RESTful API")
              .description("restFul api 文档构建利器")
              .termsOfServiceUrl("https://blog.csdn.net/m0_43584016")
              .contact("txma")
              .version("1.0")
              .build();
  }

}

三 Restful 接口

package com.kyrie.mybatis.controller;

import com.kyrie.mybatis.entity.Student;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;

/**
 * @Author: txma
 * @Date: 2019/3/31 22:06
 * @Version: 1.0
 */

@RestController
@RequestMapping(value = "/student")
@Api(description = "学生管理")
public class StudentController {

    private  int flag;
    ArrayList<Student> students = new ArrayList<>();
    @ApiOperation(value = "获取学生列表", notes = "获取所有学生信息")
    @RequestMapping(value = "/get", method = RequestMethod.GET)
    public List<Student> hello() {
        students.add(new Student("逻辑", "123456"));
        students.add(new Student("叶文杰", "123456"));
        for(Student attribute : students) {
            System.out.println(attribute);
        }

        return students;
    }

    @ApiOperation(value = "新增学生",notes = "新增学生信息")
    @RequestMapping(value = "/add",method = RequestMethod.POST)
    public  int  addStudent(Student student){
        return flag;
    }
    @ApiOperation(value = "获取学生详细信息",notes ="根据用户输入的id来查询学生的详细信息")
    @ApiImplicitParam(name = "id",value = "学生id",required = true)
    @RequestMapping(value = "user/{id}",method = RequestMethod.GET)
    public  Student getStudent(int id){
        Student student = new Student(1,"kyrie","111111");
        return  student;
    }
    @ApiOperation(value = "删除学生信息",notes = "根据id删除学生信息")
    @ApiImplicitParam(name = "id",value = "学生id",required = true)
    @RequestMapping(value = "user{/id}",method = RequestMethod.DELETE)
    public int delStudent(int id){
        return  1;
    }
 }

四 项目结构

五 运行项目，访问https://locallhost:8080/swagger-ui.html,效果如下：

Description 描述参数名称，在controller中为参数添加描述，代码如下：


至此，springboot整合swagger2来构建Api文档已经完成

六 swagger常用注解说明

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数