Swagger之集成与用法

news2025/11/4 10:00:07

简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务；

作用

1.接口的文档在线生成

2.功能测试

SpringBoot集成Swagger

1.创建一个普通的SpringBoot项目，支持web应用

2.pom中加入Maven依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spring-web</artifactId>
            <version>2.9.2</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>

3.新建接口，确保正常运行

@RestController
public class HelloController {

    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}

4.SwaggerConfig配置

@Configuration  //配置类
@EnableSwagger2 //开启Swagger2自动配置
public class SwaggerConfig {
    
}

5.测试：http://localhost:8080/swagger-ui.html

Swagger配置

1.基本配置

@Configuration  //配置类
@EnableSwagger2 //开启Swagger2自动配置
public class SwaggerConfig {
    @Bean
    public Docket docket(Environment environment){
        //设置显示swagger显示的环境
        Profiles profiles = Profiles.of("dev","test");
        //检测当前环境
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 是否开启swagger true、false
                .enable(flag)
                // 设置扫描接口
                .select()
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                        //.any() // 扫描全部的接口，默认
                        //.none() // 全部不扫描
                        .basePackage("com.lgcgk.swagger.controller") // 扫描指定包下的接口，最为常用
                        //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                        //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口
                )
                .paths(PathSelectors
                        .any() // 满足条件的路径，该断言总为true
                        //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                        //.ant("/user/**") // 满足字符串表达式路径
                        //.regex("") // 符合正则的路径
                )
                .build();
    }

    /**
     * 配置swagger信息
     * @return
     */
    private ApiInfo apiInfo(){
        //作者信息
        Contact DEFAULT_CONTACT = new Contact("lgcgk","https://blog.csdn.net/qq_35056891","1462568882@qq.com");

        return new ApiInfo("lgcgk的API文档",
                "细节决定成败",
                "v1.0",
                "https://blog.csdn.net/qq_35056891",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

2.配置API分组

在SwaggerConfig配置类的docket方法中，如果没有配置分组，默认是default。通过groupName()方法即可配置分组

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}

3.配置多个分组方法

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

常用注解

Swagger的所有注解定义在io.swagger.annotations包下

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty