Swagger框架

• 开发软件：IDEA

• 项目类型：SpringBoot的JavaWeb

• 官网：https://swagger.io/

• 在线文档：https://swagger.io/docs/specification/about/

1. 简介

• 说明：Swagger是一个用于同步生成在线Api接口文档的，可对Api接口进行描述，测试的框架

• 注意：本教程使用Swagger3.0版本，swagger页面访问路径与2.0不同

• 访问路径：http://localhost:8080/swagger-ui/index.html

• 实体类信息：只显示api接口返回值中存在的实体类的信息

2. 基本配置

（1）导入依赖

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

（2）application.yaml配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

（3）编写自动配置类

• 说明：不编写也能访问swagger页面，配置类用于对Swagger页面进行一些设置

package com.beholder1234.springbootproject1.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
 
import java.util.ArrayList;
 
@Configuration
public class SwaggerConfig {
 
    // api接口分组1
    // 用于封装配置信息，进而修改Swagger
    @Bean
    public Docket docket1(){
                            // DocumentationType Swagger版本设置
        Docket docket =
                new Docket(DocumentationType.OAS_30)
                        .apiInfo(apiInfo())
                        // 设置 swagger api接口分组名
                        .groupName("Beholder1")
                        // 是否启用 Swagger
                        // .enable(true)  // morenweitrue
                        .select()
                        // RequestHandlerSelectors 配置扫描接口的方式
                        // basePackage() 指定要扫描的包路径
                        // any()
                        // none()
                        // withClassAnnotation() 根据类上的注解进行扫描
                        // withMethodAnnotation() 根据方法上的注解进行扫描
                        .apis(RequestHandlerSelectors.basePackage("com.beholder1234.springbootproject1.controller"))
                        // 编写被过滤路径，被过滤的api不显示于Swagger
                        //  .paths(PathSelectors.ant("com.beholder1234.springbootproject1.controller"))
                        .build();
 
        return  docket;
    }
    // api接口分组2
    @Bean
    public Docket docket2(){
                            // DocumentationType Swagger版本设置
        Docket docket =
                new Docket(DocumentationType.OAS_30)
                        .apiInfo(apiInfo())
                        // 设置 swagger api接口分组名
                        .groupName("Beholder2");
        return  docket;
    }
    // 配置Swagger信息
    private ApiInfo apiInfo(){
        //作者信息 name，url，email
        Contact contact = new Contact("Beholder1234","http://148.132.12.48","906336773@qq.com");
 
        // Api信息 title descrtion version termsOfServiceUrl contact license licenseUrl
        return  new ApiInfo(
        "Beolder1234的Swagger API 文档",
        "即使再小的帆也能远航",
        "v1.0",
        "http://148.132.12.48",
        contact,
        "Apache 2.0",
        "http://148.132.12.48/licenses/LICENSE-2.0",
        new ArrayList()
        );
 
    }
}
 

（4）Swagger注解

• 说明：
  • Swagger注解的作用是对类，方法，属性进行注释，方便前端开发人员在使用Swagger的接口测试时，对该接口有清楚的认识；其对项目没有任何功能性的帮助

常用注释	应用范围	相关参数
@ApiModel	实体类上	@ApiModel(value="类名",description="类描述")
@ApiModelProperty	实体类属性上	@ApiModelProperty(value = "类属性描述",required = true,example = "属性举例",notes = "备注")
@Api	控制器类上	@Api(tags = {"tag1","tag2","..."})
@ApiOperation	控制器类的方法上	@ApiOperation(value = "功能描述",notes = "备注")
@ApiParam	控制器类的方法入参上	@ApiParam(value=”入参描述“)
@ApiImplicitParams	控制器类上	@ApiImplicitParams({@ApiImplicitParam(),@ApiImplicitParam(),...})
@ApiImplicitParam	@ApiImplicitParams内	@ApiImplicitParam(name = "参数名",value = "参数描述", required = true,paramType = "接口传参类型", dataType = "参数数据类型")
@ApiResponses	控制器类上	@ApiResponses({ @ApiResponse(),@ApiResponse(),..})
@ApiResponse	@ApiResponses内	@ApiResponse(code = ”错误代码，如404“, message = "返回信息")

（5）Swagger接口测试