前后端项目分离时，Swagger接口文档的使用

1.依赖包

 <!--swagger启动器-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

2.yml   

自定义配置，可不配，通过写配置类自己读取

#swagger自定义配置
swagger3:
  base-package: com.gmy.controller
  name: gmy
  url: https://gitee.com/
  email: 2858046082@qq.com
  version: 1.0
  group-name: gmy
  title: "接口文档标题"
  description: "swagger接口文档的描述"
  terms-of-service-url: https://gitee.com/
  license: apache
  license-url: https://gitee.com/

spring:
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: GMT+8
  mvc:
    format:
      date-time: yyyy-MM-dd HH:mm:ss
    #解决swagger3.0与springboot整合的问题
    pathmatch:
      matching-strategy: ant_path_matcher

3.config

配置读取

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Data
@Component
@ConfigurationProperties(prefix = "swagger3")
public class SwaggerProperties {
    /**
     * 扫描的包
     * 给这个包下面的接口创建文档
     */
    private String basePackage;
    /**
     * 作者姓名
     */
    private String name;
    /**
     * 作者主页链接
     */
    private String url;
    /**
     * 作者邮箱
     */
    private String email;
    /**
     * 版本号
     */
    private String version;
    /**
     * 分组名称
     */
    private String groupName;
    /**
     * 文档标题
     */
    private String title;
    /**
     * 文档描述
     */
    private String description;
    /**
     * 组织地址
     */
    private String termsOfServiceUrl;
    /**
     * 许可证
     */
    private String license;
    /**
     * 许可链接
     */
    private String licenseUrl;
}

配置

import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
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;

@Configuration
public class SwaggerConfig {

    @Autowired
    private SwaggerProperties swaggerProperties;

    /**
     * 配置swagger的信息: 设置接口路径,指定哪些接口生成文档
     * apis() 设置哪些处理请求的方法生成文档
     * 1.根据指定基础包生成文档 RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage())
     * 2.根据指定的注解生成文档 RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)
     * paths() 设置哪些请求路径生成文档
     * 1.PathSelectors.any() 所有路径
     * 2.PathSelectors.ant("/dept/**") 匹配规则的路径
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(getApiInfo())
                .select()
                // .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage())
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // .paths(PathSelectors.ant("/dept/**"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 配置swagger的标题,描述,联系人(文档的作者)等信息
     */
    private ApiInfo getApiInfo(){
        //创建联系人对象
        Contact contact = new Contact(swaggerProperties.getName(), swaggerProperties.getUrl(), swaggerProperties.getEmail());
        return new ApiInfoBuilder()
                .contact(contact)
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .version(swaggerProperties.getVersion())
                .license(swaggerProperties.getLicense())
                .licenseUrl(swaggerProperties.getLicenseUrl())
                .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
                .build();
    }

Controller与entity

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("学生实体")
public class Student {

    @ApiModelProperty("学生注解")
    private Integer id;
    @ApiModelProperty("学生姓名")
    private String name;
    @ApiModelProperty("学生地址")
    private String address;
    @ApiModelProperty("学生生日")
    private Date birthday;
}

@RestController
@RequestMapping("/student")
@Api(tags = "学生信息接口")
public class StudentController {

    @ApiOperation("学生信息分页与条件查询")
    /**
     * @ApiImplicitParam 描述入参(请求参数)
     * paramType用于描述参数的类型
     * 1.query 路径拼接传参
     * 2.path 路径传参
     * 3.body 请求体传参(名值对)
     */
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNumber", value = "当前页码", required = false, dataTypeClass = Integer.class,
                    defaultValue = "1", paramType = "query"),
            @ApiImplicitParam(name = "pageSize", value = "每页条数", required = false, dataTypeClass = Integer.class,
                    defaultValue = "10", paramType = "query")
    })
    @ApiResponses({
            @ApiResponse(code = 0, message = "成功"),
            @ApiResponse(code = -1, message = "失败")
    })
    @GetMapping("/page")
    public Result page(@RequestParam(value = "pageNumber", required = false, defaultValue = "1") Integer pageNumber,
                       @RequestParam(value = "pageSize", required = false, defaultValue = "10") Integer pageSize,
                       Student student){
        System.out.println(pageNumber);
        System.out.println(pageSize);
        System.out.println(student);
        return Result.success();
    }

    @ApiOperation("学生信息根据主键查询")
    @ApiImplicitParam(name = "id", value = "学生主键", required = true, dataTypeClass = Integer.class, paramType = "path")
    @GetMapping("/get/{id}")
    public Result getById(@PathVariable("id") Integer id){
        System.out.println(id);
        return Result.success();
    }

    @ApiOperation("学生信息新增")
    @PostMapping("/save")
    public Result save(@RequestBody Student student){
        System.out.println(student);
        return Result.success();
    }

    @ApiOperation("学生信息编辑")
    @PutMapping("/edit")
    public Result edit(@RequestBody Student student){
        System.out.println(student);
        return Result.success();
    }

    @ApiOperation("学生信息根据主键删除")
    @ApiImplicitParam(name = "id", value = "学生主键", required = true, dataTypeClass = Integer.class, paramType = "path")
    @DeleteMapping("/remove/{id}")
    public Result removeById(@PathVariable("id") Integer id){
        System.out.println(id);
        return Result.success();
    }
}