Swagger_swagger框架-CSDN博客

本文链接：https://blog.csdn.net/weixin_63691530/article/details/142366439

1.什么是Swagger？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

2.Swagger的作用：

接口的文档在线自动生成
功能测试

3.Swagger的使用：

导入相关依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

启动类中添加@EnableSwagger2注解：@EnableSwagger2是springfox提供的注解，代表Swagger2相关技术的开启，会扫描所在包，以及子包中所有的类型的注解，做swagger文档的定值。

写一个api接口

@RestController
public class HelloController {
    
    @GetMapping("/get")
    public String get() {
        return "get";
    }
    
    @PostMapping("/post")
    public String post() {
        return "post";
    }
    
    @RequestMapping("/hello")
    public String hello() {
        return "hello";
    }
}

Swagger的基础信息配置控制类

@Configuration
@EnableSwagger2 //开启swagger2,若启动类上添加了该注解，则配置类可以不添加
public class SwaggerConfig {

    // 创建swagger bean
    @Bean
    public Docket docket() {
        // Docket是swagger全局配置对象
        // DocumentationType：指定文档类型为swagger2
        return new Docket(DocumentationType.SWAGGER_2)
                // swagger信息
                .apiInfo(apiInfo());
    }

    // swagger文档信息
    public ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact(
                // 文档发布者的名称
                "iqiuq",
                // 文档发布者的网站地址
                "https://iqiuq.gitee.io/qiuqblogs/",
                // 文档发布者的电子邮箱
                "qiuyonghui258@163.com"
        );
        return new ApiInfo(
                // 标题
                "iqiuq swagger api",
                // 文档描述
                "演好自己人生的剧本",
                // 版本号
                "1.0",
                // 服务组url地址
                "urn:tos", 
                // 作者信息
                contact,
                // 开源组织
                "Apache 2.0",
                // 开源地址
                "http://www.apache.org/licenses/LICENSE-2.0",
                // 集合
                new ArrayList()
        );
    }
}

Swagger扫描包配置

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {

    // 创建swagger bean
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                // swagger信息
                .apiInfo(apiInfo())
                // swagger 扫描包配置
                // select()获取Docket中的选择器，返回ApiSelectorBuilder构造选择器，如扫描扫描包的注解
                .select()
                /**
                 * requestHandlerSelectors：请求处理选择器
                 * basePackage()：扫描指定包下的所有接口
                 * any()：扫描所有的包
                 * none()：不扫描
                 * withClassAnnotation()：扫描指定类上的注解，参数是一个注解的放射对象
                 * withMethodAnnotation()：扫描方法上的注解
                 */
                // 指定扫描器扫描的规则（断言）
                .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller"))
                /**
                 * pathSelectors：路径选择器，过滤路径
                 * ang()：选择所有路径
                 * none()：都不选择
                 * ant()：选择指定路径
                 * regex()：正则表达式
                 */
                .paths(PathSelectors.regex("/hello"))
                .build();
    }
        return new ApiInfo(
                // 标题
                "iqiuq swagger api",
                // 文档描述
                "演好自己人生的剧本",
                // 版本号
                "1.0",
                // 服务组url地址
                "urn:tos", 
                // 作者信息
                contact,
                // 开源组织
                "Apache 2.0",
                // 开源地址
                "http://www.apache.org/licenses/LICENSE-2.0",
                // 集合
                new ArrayList()
        );
}

配置是否开启swagger

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {

    // 创建swagger bean
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                // swagger信息
                .apiInfo(apiInfo())
                // 配置是否开启swagger，若为false，则浏览器不能访问
                .enable(false);
    }

    // swagger文档信息
    public ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact(
                "iqiuq",
                "https://iqiuq.gitee.io/qiuqblogs/",
                "qiuyonghui258@163.com");
        return new ApiInfo(
                "iqiuq swagger api",
                "演好自己人生的剧本",
                "1.0",
                "urn:tos", contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

开发和测试环境中开启swagger，其他环境不开启

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {

    // 创建swagger bean
    @Bean
    public Docket docket(Environment environment) {
        // 配置swagger的docket的bean实例
        Profiles profiles = Profiles.of("dev","test");
        // 通过environment.acceptsProfiles()判断是否指定的环境中，是，则为true
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller"))
                .paths(PathSelectors.regex("/hello"))
                .build();
    }

    // swagger文档信息
    public ApiInfo apiInfo() {
        Contact contact = new Contact(
                "iqiuq",
                "https://iqiuq.gitee.io/qiuqblogs/",
                "qiuyonghui258@163.com");
        return new ApiInfo(
                "iqiuq swagger api",
                "演好自己人生的剧本",
                "1.0",
                "urn:tos", 
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

swagger分组配置

每个组就是一个docket实例，多个组就是创建多个docket的实例

@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {

    // 创建swagger bean
    @Bean
    public Docket docket1(Environment environment) {
        // 配置swagger的docket的bean实例
        Profiles profiles = Profiles.of("dev","test");
        // 通过environment.acceptsProfiles()判断是否指定的环境中，是，则为true
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                // swagger信息
                .apiInfo(apiInfo())
                // 配置是否开启swagger，若为false，则浏览器不能访问
                .enable(flag)
                // 配置组名
                .groupName("iqiuq")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller"))
                .paths(PathSelectors.regex("/hello"))
                .build();
    }

    @Bean
    public Docket docket2(Environment environment) {
        Profiles profiles = Profiles.of("dev","test");
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .groupName("哈哈哈")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller"))
                .paths(PathSelectors.regex("/hello"))
                .build();
    }

    @Bean
    public Docket docket3(Environment environment) {
        Profiles profiles = Profiles.of("dev","test");
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .groupName("嘻嘻嘻")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller"))
                .paths(PathSelectors.regex("/hello"))
                .build();
    }
    // swagger文档信息
    public ApiInfo apiInfo() {
        Contact contact = new Contact(
                "iqiuq",
                "https://iqiuq.gitee.io/qiuqblogs/",
                "qiuyonghui258@163.com");
        return new ApiInfo(
                "iqiuq swagger api",
                "演好自己人生的剧本",
                "1.0",
                "urn:tos", 
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

启动项目，并在浏览器输入http://localhost:8080/swagger-ui.html进行swagger-ui界面访问