SpringBoot-Swagger3

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger让部署管理和使用功能强大的API变得非常简单。

Swagger要解决的问题

前后端分离：

• 前端 -> 前端控制层、视图层
• 后端 -> 后端控制层、服务层、数据访问层
• 前后端通过API进行交互
• 前后端相对独立且松耦合

产生的问题

前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发。

解决方案-Swagger

Swagger

• 号称世界上最流行的API框架

• Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新

• 直接运行，在线测试API

• 支持多种语言 （如：Java，PHP等）

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

Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

1、添加依赖

        <!-- 引入swagger3包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

【注】SpringBoot 版本为2.6.4时会报错，所以降低SpringBoot的版本

2、新建配置类SwaggerConfig java

//访问地址： http://localhost:9090/swagger-ui/index.html

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    // Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger
    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("标准接口")
                .apiInfo(apiInfo("Spring Boot中使用Swagger2构建RESTful APIs", "1.0"))
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.whey.springboot.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://ip:port/swagger-ui.html
     *
     * @return
     */
    // 可以通过apiInfo()属性配置文档信息
    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfoBuilder()
                .title(title)
                .description("更多请关注: https://blog.csdn.net/xqnode")
                .termsOfServiceUrl("https://blog.csdn.net/xqnode")
                .contact(new Contact("xqnode", "https://blog.csdn.net/xqnode", "xiaqingweb@163.com"))
                .version(version)
                .build();
    }
}

3、问题1

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    // Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger
    @Bean
    public Docket restApi(Environment environment) {

        // 设置要显示swagger的环境
        Profiles of = Profiles.of("dev", "test");//test环境不存在也可以写
        // 判断当前是否处于该环境
        // 通过 enable() 接收此参数判断是否要显示
        boolean b = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("标准接口")
                .apiInfo(apiInfo("Whey使用Swagger构建RESTful APIs", "1.0"))
//                .enable(b)  // 如果是false，swagger将不能在浏览器中访问了
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .select()
                // RequestHandlerSelectors：配置要扫描接口的方式
                .apis(RequestHandlerSelectors.basePackage("com.why.swagger.controller"))
                .paths(PathSelectors.any()) // 过滤什么路径
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://ip:port/swagger-ui.html
     *
     * @return
     */
    // 可以通过apiInfo()属性配置文档信息
    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfoBuilder()
                .title(title)
                .description("我的博客: https://blog.csdn.net/qq_44989062?type=lately")
                .termsOfServiceUrl("https://blog.csdn.net")
                .contact(new Contact("whey", "https://blog.csdn.net/qq_44989062?type=lately", "whey820@163.com"))
                .version(version)
                .build();
    }
}

4、问题2

如果没有配置分组，默认是default。通过groupName()方法即可配置分组

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }

5、实体类配置

@ApiModel("用户实体类")    // 为类添加注释
public class User {
        @ApiModelProperty("用户名")    // 为属性添加注释
        public String name;
        @ApiModelProperty("密码")
        public String password;
}

@RestController
@Api(description="讲师管理")
public class helloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello,Swagger!";
    }

    // 只要我们的接口中，返回值中存在实体类，它就会被扫描到Swagger中
    @PostMapping("/getUser")
    public User getUser(){
        return new User();
    }

    @ApiOperation("hello控制类")
    @GetMapping("/hello1")
    public String hello1(String username){
        return "hello" + username;
    }
}

 6、使用第三方UI

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

访问路径变为：localhost//doc.html