swagger——接口文档

一、序言

本文章主要应用于记录自身学习笔记，若有错误，还望大佬指出。

二、基本介绍

  swagger是一个规范定义REST ful接口文档的工具，通过使用注解与配置的方式将项目中写好的接口进行规范化展示，避免前后端因为接口不统一而出现数据交互失误。
  据说Apifox在接口文档管理方面还要优于swagger，还可进行mock数据，不过因本人对这个工具还没有过具体的了解，也就不多谈及。
  本文以介绍swagger为主，不对其他代码做详细补充。

三、常用注解

注解	作用
@Api	用在请求的类上，例如XXXController，表示对类的说明
@ApiMondel	通常用在实体类上，表示返回的响应数据的信息
@ApiModelProperty	用于属性上，指定响应类的属性
@ApiOperation	用于请求的方法上，说明方法用途、作用
@ApiImplicitParams	用在请求的方法上，表示一组参数说明
@ApiImplicitParam	用在@ApiImplicitParams中，指定一个请求参数的方面，如返回类型，参数介绍等

四、使用过程

  本文主要以swagger3.0.0为主，其与以往的swagger存在一定差异，本文中会指出目前我所知晓的差异。

1、导入依赖

• 前提条件

        <!--web项目，优先导入-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!--减少代码量-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

• swagger3.0.0

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-boot-starter</artifactId>
	<version>3.0.0</version>
</dependency>

• swagger3.0.0以下版本

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <!--版本任意-->
            <version>XXX</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <!--版本任意-->
            <version>XXX</version>
        </dependency>

2、进行application.yml文件配置

  自springBoot 2.6后使用swagger需要配置路径，不然会报错，启动失败。

server:
  # 默认也为8080端口
  port: 8080
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher # 匹配路径，不然会报错， Failed to start bean ‘documentationPluginsBootstrapper‘

3、开发实体类和配置类

  利用swagger注解对相应内容进行标注，便捷的开发接口文档。

• 实体类User

package swagger.demo.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * User实体类
 */
@Data
@ApiModel(value = "用户实体", description = "[描述] 用户实体")
@AllArgsConstructor
@NoArgsConstructor
public class User {

    @ApiModelProperty(value = "用户id,主键")
    private Integer id;

    @ApiModelProperty(value = "年龄")
    private Integer age;

    @ApiModelProperty(value = "姓名")
    private String name;

}

• 用户控制器UserController

package swagger.demo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import swagger.demo.entity.User;

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

/**
 * 用户控制器
 */
@Api(tags = "用户控制器")
@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping("/getAllUsers")
    @ApiOperation(value = "获取所有用户", notes = "获取所有用户信息")
    public List<User> getAllUserInfo(){
        User user = new User(1, 18, "张三");
        List<User> userList = new ArrayList<>();
        userList.add(user);
        return userList;
    }



    @GetMapping("/page/{pageNum}/{pageSize}")
    @ApiOperation(value = "分页查询")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNum", value = "页码",
            required = true, type = "Integer"),
            @ApiImplicitParam(name = "pageSize", value = "页条数",
            required = true, type = "Integer")
    })
    public String findByPage(@PathVariable Integer pageNum,
                             @PathVariable Integer pageSize){
        return "ok";
    }

}

• 开发配置类SwaggerConfiguration

package swagger.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * 配置类，配置分组，接口详情等
 */
@Configuration
@EnableOpenApi
public class SwaggerConfiguration {

    @Bean
    public Docket createUserApi(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("用户接口组")
                .select()
                .apis(RequestHandlerSelectors.basePackage("swagger.demo.controller"))
                .build();
        return docket;
    }

    /*
    * 可以创建其他bean来配置其他分组
    * 与createUserApi()类似
    * */


    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("标题")
                .contact(new Contact("name", "url", "email"))
                .version("版本号")
                .description("描述信息")
                .build();
    }

}

配置类中也可以不设其他方法
去掉groupName()分组，包路径修改为所有控制类的根路径
即可全部分到默认的default组

swagger3.0.0的配置类中所需注解为@EnableOpenApi
其他较低版本为@EnableSwagger2

4、访问页面

• swagger3.0.0： http://localhost:端口号/swagger-ui/index.html
• 其他较低版本：http://localhost:端口号/swagger-ui.html
• 效果如下：
  

五、存在的问题

  swagger运行时会报错java.lang.NumberFormatException: For input string: ““，存在格式异常，据悉是因为在swagger内部未对空串做排查，作为一个摆烂之王，我也就懒得去探查解决的方法了，希望各位大佬能提出解决方案以及本文存在的其他问题，万分感谢。