SpringBoot整合Swagger生成接口文档

痛定思痛。 2022-04-23 11:54 406阅读 0赞

# 介绍: #

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.项目结构 ###

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTk0MTQ2_size_16_color_FFFFFF_t_70][]

### 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的更多注解的使用: ###

![20190218142509664.png][]

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

![20190218142421984.png][]

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

### 7.示例 ###

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTk0MTQ2_size_16_color_FFFFFF_t_70 1][]

### 点赞或者评论是我最大的动力,有问题欢迎留言或者联系q:1559810637   ###

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTk0MTQ2_size_16_color_FFFFFF_t_70]: /images/20220319/6244f497c14d44d493c63528455f4a8c.png
[20190218142509664.png]: /images/20220319/ef91770c437343d9acb8167e14f57eb4.png
[20190218142421984.png]: /images/20220319/03a6dcc08b304342a51d58a2fbff2004.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQxNTk0MTQ2_size_16_color_FFFFFF_t_70 1]: /images/20220319/01acdf5dfd7e4253b60e6181b34e2266.png