SpringBoot学习 — 集成Swagger

目录

Swagger介绍

SpringBoot 集成 Swagger

环境搭建

配置Swagger

配置API分组

实体配置

---

Swagger介绍

前后端分离

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

但是，前后端集成时，前端或后端无法做到“及时协商”，最终导致问题集中爆发。

解决方案：Swagger等

Swagger

• 流行的API框架
• Restful API 文档在线自动生成器：API文档与API定义同步更新
• 直接运行，在线测试API
• 支持多种语言

SpringBoot 集成 Swagger

环境搭建

1.新建一个SpringBoot-web项目

2.在pom.xml中添加 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>

3.编写HelloController ，测试环境是否成功

4.要使用Swagger，我们需要编写一个配置类 — SwaggerConfig 来配置Swagger

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

}

5.访问测试 http://loaclhost:8080/swagger-ui.html

成后访问之后，可以看到如下界面：

 

配置Swagger

1. Swagger 实例 Bean是Docket，所有通过配置Docket实例来配置Swagger。

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2);
    }

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

    //配置Swagger 信息 apiInfo
    public ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("大敏", "https://blog.csdn.net/queen00000", "1841463143@qq.com");

        return new ApiInfo(
                "大敏的Swagger API文档",
                "所有的努力都只为遇见更好的自己",
                "v1.0",
                "https://blog.csdn.net/queen00000",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

3.Docket 实例关联上 apiInfo()

    //配置Swagger的Docket bean实例
    @Bean
    public Docket docket(Environment environment){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
    }

4.重启项目，可以查看配置效果

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

    //配置Swagger的Docket bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger 环境
        Profiles profiles = Profiles.of("dev");
        //通过environment.acceptsProfiles() 判断当前是否处于 设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable：是否启用swagger
                //.enable(flag)
                .groupName("大敏")
                .select()
                /*
                 * RequestHandlerSelectors 配置要扫描接口的方式
                 * basePackage()：指定要扫描的包
                 * any()：扫描全部
                 * none()：不扫描
                 * withClassAnnotation()：扫描类上的注解，参数是一个注解的反射对象
                 * withMethodAnnotation()：扫描方法上的注解
                 */
                .apis(RequestHandlerSelectors.basePackage("com.damin"))
                //paths()：过滤路径
                //.paths(PathSelectors.ant("/damin/**"))
                .build();
    }

    //配置Swagger 信息 apiInfo
    public ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("大敏", "https://blog.csdn.net/queen00000", "1841463143@qq.com");

        return new ApiInfo(
                "大敏的Swagger API文档",
                "所有的努力都只为遇见更好的自己",
                "v1.0",
                "https://blog.csdn.net/queen00000",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

 

配置API分组

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

    @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("大敏")
    }

2.配置多个分组

只需要配置多个docket即可：

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

    @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");
    }
}

实体配置

1.新建实体类

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("密码")
    private String password;
    ...
}

2.只要这个实体在请求接口的返回值上，都能映射到实体项中

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

3.启动查看