SpringBoot整合Swagger生成接口文档

介绍:

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。 如果想深入分析项目源码，了解更多内容，见参考资料。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

使用

1.maven依赖

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

        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>2.0.0</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

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

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>

        <dependency>
            <groupId>tk.mybatis</groupId>
            <artifactId>mapper-spring-boot-starter</artifactId>
            <version>2.1.4</version>
        </dependency>

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

    </dependencies>

2.application.yml

spring:
  datasource:
    username: root
    password: root
    url: jdbc:mysql://127.0.0.1:3306/test?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8
    driver-class-name: com.mysql.cj.jdbc.Driver

    initialSize: 5
    minIdle: 5
    maxActive: 20
    maxWait: 60000
    timeBetweenEvictionRunsMillis: 60000
    minEvictableIdleTimeMillis: 300000
    validationQuery: SELECT 1 FROM DUAL
    testWhileIdle: true
    testOnBorrow: false
    testOnReturn: false
    poolPreparedStatements: true

3.swagger配置类

package com.hw.springbootswagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

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

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @program: springboot-swagger
 * @description:
 * @author: hw
 * @create: 2019-02-18 13:33
 **/
@Configuration
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hw.springbootswagger.controller"))//扫描包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")//标题提示
                .description("https://blog.csdn.net/qq_41594146")
                .termsOfServiceUrl("https://blog.csdn.net/qq_41594146")
                .version("1.0")
                .build();
    }
}

4.主启动类

package com.hw.springbootswagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import springfox.documentation.swagger2.annotations.EnableSwagger2;
import tk.mybatis.spring.annotation.MapperScan;

@MapperScan("com.hw.springbootswagger.mapper")//tkmapper
@SpringBootApplication
@EnableSwagger2//swagger
public class SpringbootSwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootSwaggerApplication.class, args);
    }

}

5.项目结构

6.controller层

package com.hw.springbootswagger.controller;

import com.hw.springbootswagger.entity.Person;
import com.hw.springbootswagger.mapper.PersonMapper;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

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

/**
 * @program: springboot-swagger
 * @description:
 * @author: hw
 * @create: 2019-02-18 13:25
 **/
@RestController
@RequestMapping("test")
@Api(value = "测试接口Controller")//类注解
public class PersonController {

    @Autowired
    PersonMapper personMapper;

    @ApiOperation(value = "通过学生id查找学生", notes = "测试用接口")//方法说明
    @ApiImplicitParam(name = "id", value = "用户id", dataType = "Integer", required = true, paramType = "path")//参数说明
    @GetMapping("/get/{id}")
    public Person get(@PathVariable("id") int id) {
        Person person = personMapper.selectByPrimaryKey(id);
        return person;
    }


    @ApiOperation(value = "查找全部学生")
    @GetMapping("/getAll")
    public List<Person> getAll(){
        List<Person> people = personMapper.selectAll();
        return people;
    }

    @ApiOperation(value = "根据id删除学生")
    @ApiImplicitParam(name = "id",value = "用户id",dataType = "Integer",required = true)
    @DeleteMapping("delete/{id}")
    public int remove(@PathVariable int id){
        int i = personMapper.deleteByPrimaryKey(id);
        return i;
    }

    @ApiOperation(value = "添加学生")
    @ApiImplicitParam(name = "person",value = "学生对象",dataType = "Person",required = true)
    @PostMapping("/post")
    public int post(Person person){
        int insert = personMapper.insert(person);
        return insert;
    }


    @ApiOperation(value = "修改学生")
    @ApiImplicitParam(name = "person",value = "学生对象",dataType = "Person",required = true)
    @PostMapping("/put")
    public int put(Person person){
        int insert = personMapper.updateByPrimaryKeySelective(person);
        return insert;
    }
}

关于swagger的更多注解的使用:

点击这个包下,然后看见下图的内容,点进去你想了解的注解,通过人家写的注释可以知晓注解和其参数的作用

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

7.示例