[学习笔记] SpringBoot之整合Swagger

# 学习 # · 2021-09-29

Swagger

1、Swagger:是一套基于OpenAPI规范(OpenAPI Specification,OAS)构建的开源工具,号称世界上最流行的API框架。

2、Swagger Codegen:可以将描述文件生成HTML格式和CWIKI形式的接口文档,同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包,docker,node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

3、Swagger UI:提供了一个可视化的UI页面展示描述文件。

4、Swagger Editor:编辑Swagger描述文件的编辑器。

5、Swagger Inspector:可以对接口进行测试。

6、Swagger Hub:集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub中。

7、Springfox Swagger:是Spring社区维护的一个项目。Spring 基于swagger规范,可以将基于SpringMVC和Spring Boot项目的项目代码,自动生成JSON格式的描述文件。


SpringBoot整合Swagger3的步骤

1、新建SpringBoot-Web项目。

2、导入Swagger依赖。

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

3、创建HelloWorldController。

@RestController
public class HelloWorldController {
    @GetMapping("/hello")
    public String hello() {
        return "success";
    }
}

4、创建Swagger配置类。

@Configuration // 配置类
@EnableOpenApi // 开启Swagger的自动配置
public class SwaggerConfiguration {

}

5、访问Swagger页面。

6、Swagger2和Swagger3的配置差异:

(1)SpringBoot项目整合swagger2需要用到两个依赖:springfox-swagger2和springfox-swagger-ui,用于自动生成swagger文档。

(2)Swagger3添加注解@EnableOpenApi,Swagger2是添加注解@EnableSwagger2

(3)Swagger3和Swagger2的访问地址不同。


Swagger配置

1、Swagger配置类常见配置内容:

(1)通过配置Docket实例来配置Swaggger。

(2)可以通过apiInfo()属性配置文档信息。

@Configuration // 配置类
@EnableOpenApi // 开启Swagger的自动配置
public class SwaggerConfiguration {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 配置是否启用Swagger,如果是false,在浏览器将无法访问
                .enable(true)
                // 通过.select()方法,去配置扫描接口
                .select()
                // RequestHandlerSelectors配置要扫描接口的方式
                // basePackage(): 指定要扫描的包
                // any(): 扫描全部
                // none(): 不扫描
                // withClassAnnotation(): 扫描类上的注解,参数是一个注解的反射对象
                // withMethodAnnotation(): 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.duo.controller"))
                // path():过滤什么路径
                //.paths(PathSelectors.ant("/controller/**"))
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("多仔", "https://www.l5v.cn/", "[email protected]");
        return new ApiInfo(
                "Swagger API接口文档", // 标题
                "测试项目的Swagger API接口文档", // 描述
                "v2.0", // 版本
                "https://www.l5v.cn/", // 组织链接
                contact, // 联系人信息
                "Apache 2.0 许可", // 许可
                "http://www.apache.org/licenses/LICENSE-2.0", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

2、Swagger常用注解:

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

(1)Model上的注解:

@ApiModel("用户实体")
public class UserPojo {
    @ApiModelProperty("用户名")
    public String username;

    @ApiModelProperty("密码")
    public String password;

    // 省略有参无参get/set
}

(2)Controller上的注解:

@RestController
@Api(tags = "HelloWorld控制类")
public class HelloWorldController {
    @ApiOperation("获取用户信息接口")
    @GetMapping("/getUser")
    public UserPojo getUser() {
        return new UserPojo("admin", "admin");
    }

    @ApiOperation("欢迎信息接口")
    @GetMapping("/hello")
    public String hello(@ApiParam(value = "用户名" ,required = true) String username) {
        return "欢迎你," + username;
    }
}

(3)查看效果:

3、Swagger配置生产环境与正式环境:

//获取当前环境需要用到environment对象
@Bean
public Docket docket(Environment environment){
    //设置要显示的Swagger环境,是否处于dev或test环境
    Profiles profiles = Profiles.of("dev","test");

    // spring.profiles.active=dev

    //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        //是否开启swagger
        .enable(flag)
// 省略其他代码

4、配置SwaggerAPI文档分组:

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        // ...
        .groupName("李华")
        .enable(false);
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("李四")
            // ...
            .enable(true);
    }

// ...

}
如无特殊说明,本博所有文章均为博主原创。

如若转载,请注明出处:一木林多 - https://www.l5v.cn/archives/306/

评论