Swagger

简介

Swagger 它是一个帮助开发人员来简化开发 RESTFUL API 的一款开发工具，其核心是基于 NPM 实现，在 Spring 项目中则是通过封装 SpringFox 依赖来完成对接口请求方式、请求参数、响应数据的加载，最终通过前端界面的方式来展现给用户。 Swagger 具有简单、方便、高效的特性，用 Swagger 构建 RESTFUL API 可快速又方便。

demo

创建项目

创建普通springboot项目

依赖

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

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

配置类

config包下创建SwaggerConfig

@EnableOpenApi  //启用swagger
@Configuration //标识配置类
public class SwaggerConfig {
}

测试

地址：http://localhost:8080/swagger-ui/index.html

基本配置

@EnableOpenApi
@Configuration
public class SwaggerConfig {

    /**
     * swagger的配置类 --》 Docket
     * @return Docket
     */
    @Bean
    public Docket docket(Environment environment){
        Profiles of = Profiles.of("dev", "test");
        //如果配置环境包含这两，就为ture
        boolean flag = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.OAS_30)
                //apiInfo 配置一些常见信息
                .apiInfo(apiInfo())
                //是否使用swagger, 根据环境来使用swagger
                .enable(flag)
                //分组名称
                .groupName("1组")
                //配置扫描路径，只扫描那个包下的接口
                .select().apis(RequestHandlerSelectors.basePackage("com.qc.swagger.controller"))
                //配置扫描路径 .any() 所有  none()都不 regex(final String pathRegex)正则  ant(final String antPattern)给定路径
                .paths(PathSelectors.any()).build();
    }

    /**
     * 分组 配置多个Docket就好
     * @return Docket
     */
    @Bean
    public Docket docket2(Environment environment){
        Profiles of = Profiles.of("dev", "test");
        //如果配置环境包含这两，就为ture
        boolean flag = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.OAS_30)
                //apiInfo 配置一些常见信息
                .apiInfo(apiInfo())
                //是否使用swagger, 根据环境来使用swagger
                .enable(flag)
                //分组名称
                .groupName("2组")
                //配置扫描路径，只扫描那个包下的接口
                .select().apis(RequestHandlerSelectors.basePackage("com.qc.swagger.controller"))
                .build()
                ;
    }

    /**
     * api简介信息
     * ApiInfo 只提供了有参构造，所以需要全部
     * @return ApiInfo
     */
    private ApiInfo apiInfo(){
        return new ApiInfo(
                //标题
            "swagger的demo",
                //描述
                "这里是描述信息",
                //版本号
                "2.0",
                //服务条款网址
                "https:qicong77.com",
                //作者信息
                new Contact("c","https:qicong77.com","123456@qq.com"),
                //协议-执照
                "Apache 2.0",
                //许可证网址
                "http://www.apache.org/licenses/LICENSE-2.0",
                //一些扩展
                new ArrayList<>()
        );
    }

    
}

常用注解

//@ApiImplicitParam参数
 @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
       paramType：参数放在哪个地方
       header-->请求参数的获取：@RequestHeader
       query-->请求参数的获取：@RequestParam
       path（用于restful接口）-->请求参数的获取：@PathVariable
       body（不常用）
       form（不常用）
       name：参数名
       dataType：参数类型
       required：参数是否必须传
       value：参数的意思
       defaultValue：参数的默认值


// @ApiResponse	
	code：数字，例如400
	message：信息，例如"请求参数没填好"
	response：抛出异常的类