Swagger学习

Swagger学习

学习目标：

• 了解Swagger的作用和概念
• 了解前后端分离
• 在SpringBoot中集成Swagger

Swagger简介

前后端由不分离到分离：

Swagger

Springboot集成Swagger

步骤

1、创建一个springboot项目，导入web依赖

2、导入依赖

<!-- 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、编写一个Hello工程

4、配置Swagger-->Config

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

}

5、测试运行

访问地址：Swagger UI

配置Swagger

Swagger的bean实例：Docket

 @Bean
public Docket docket(){
    return  new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo());
}
//配置Swagger信息：apiInfo
private ApiInfo apiInfo(){
    //联系人（作者信息）
    Contact contact = new Contact("让时间变成力量", "https://i.cnblogs.com/articles", "2743338099@qq.com");
    ApiInfo apiInfo = new ApiInfo(
        "yfm学Swagger",
        "yfm看狂神学Swagger",
        "1.0",
        "https://i.cnblogs.com/articles",
        contact,
        "Apache 2.0",
        "http://www.apache.org/licenses/LICENSE-2.0",
        new ArrayList<VendorExtension>());
    return apiInfo;
}

Swagger配置扫描接口

Docket()

@Bean
public Docket docket(){
    return  new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        //RequestHandlerSelectors 配置要扫描接口的方式
        //basePackage()指定要扫描的包
        //any()表示扫描所有包
        //none()表示不扫描包
        //withMethodAnnotation(GetMapping.class)   为方法上有指定注解的方法生成接口文档
        //withClassAnnotation(RestController.class)  为类上有指定注解的类生成接口文档
        .apis(RequestHandlerSelectors.basePackage("swagger"))
        //paths() :过滤什么路径
        //ant 指定路径过滤
        .paths(PathSelectors.ant("/swagger")) 
        .build();
}

Swagger设置开启开关

@Bean
public Docket docket(Environment environment){
    //只有在dev 或 test环境下才能开启Swagger2
    Profiles profiles = Profiles.of("dev", "test");
    boolean flag = environment.acceptsProfiles(profiles);
    
    return  new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .enable(flag)
        .select()
        //RequestHandlerSelectors 配置要扫描接口的方式
        //basePackage()指定要扫描的包
        //any()表示扫描所有包
        //none()表示不扫描包
        //withMethodAnnotation(GetMapping.class)   为方法上有指定注解的方法生成接口文档
        //withClassAnnotation(RestController.class)  为类上有指定注解的类生成接口文档
        .apis(RequestHandlerSelectors.basePackage("swagger"))
        //paths() :过滤什么路径
        //ant 指定路径过滤
        //                .paths(PathSelectors.ant("/swagger"))
        .build();
}

Swagger分组和接口注释

配置API文档的分组

.groupName("yfm");// 设置组名，谁写的代码，谁就管理对应的api文档

如何设置多个分组？ 多个Docket实例即可

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

实体类配置（给实体类加注释信息）:

需要在controller的方法中使用实体类，才能显示在文档中

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", password='" + password + '\'' +
                '}';
    }
}

@PostMapping("/user")
public User user(User user){
    return user;
}

controller配置（给实体类加注释信息）：

@RestController
public class MyController {
    @ApiOperation("hello方法")
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    @ApiOperation("user方法")
    @PostMapping("/user")
    public String user(@ApiParam("用户名") String username){
        System.out.println("q");
        return username;
    }
}

Swagger在线测试代码

启动项目，可以直接在swagger上测试Controller层的代码

总结

注意点:在正式发布的时候关闭swagger,一是出于安全考虑，二是出于节省内存