Swagger学习笔记（2020-11-17）

Swagger学习（2020-11-17）

首次使用

1.创建一个Spring Boot -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.0.0无法访问http://localhost:8080/swagger-ui.html-->

3.编写helloword

4.配置Swagger->config

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

5.测试运行：http://localhost:8080/swagger-ui.html

配置swagger

Swagger的bean实例Docket；

//配置Swagger的Docket的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo());
}

//配置Swagger信息 apiInfo
public ApiInfo apiInfo(){
    
    //作者信息
    Contact contact = new Contact("程", "http://www.baidu.com","CodeOfJie@163.com");
    return new ApiInfo(
            "程菜鸡学习SwaggerAPI文档", 
            "Api Documentation：描述", 
            "1.0", 
            "http://www.baidu.com", 
            contact, 
            "Apache 2.0", 
            "http://www.apache.org/licenses/LICENSE-2.0", 
            new ArrayList());
}

Swagger配置扫描接口

Docket.select()
  
  public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                /*
                *RequestHandlerSelectors 配置要扫描接口的方式
                *1.basePackage 指定扫描的包 ---> 一般使用这个
                *2.any()：扫描全部    none()：都不扫描 
                *3.withClassAnnotation：扫描类上的注解
                *4.withMethodAnnotation：扫描方法上的注解
                */
                .apis(RequestHandlerSelectors.basePackage("com.cheng.controller"))
                //过滤什么路径
                .paths(PathSelectors.ant("/cheng/**"))
                .build();
    }

配置是否启动Swagger

//配置Swagger的Docket的bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            //enable: 
            // false--->关闭Swagger，浏览器不能使用
            //true--->开启
            .enable(false)
            .select()  
            .apis(RequestHandlerSelectors.basePackage("com.cheng.controller"))
            .build();
}

题目：只希望Swagger在生产环境中使用，在发布的时候不使用

解决：

1.判断是否是生产环境

2.注入enable（flag）

 //设置要显示的Swagger环境
 Profiles profiles = Profiles.of("dev","test");
 //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
 boolean flag = environment.acceptsProfiles(profiles);
 new Docket.enable(flag)

配置api文档的分组

.groupName("程菜鸡")

问：如何配置多个组？

解：多个Dockct实例即可

@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("docket1组");
}

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("docket2组");
}

@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("docket3组");
}

Swagger接口API和测试

User

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


    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

controller

package com.cheng.controller;

import com.cheng.controller.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @描述
 * @创建时间 2020/11/16
 */

@RestController
public class HelloController {

    //ApiOperation 方法注释
    @ApiOperation("欢迎")
    @RequestMapping("/hello")
    public String hello(){
        return "hello,world!";
    }

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

    @ApiOperation("hello2方法")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello"+username;
    }

    @ApiOperation("psot测试方法")
    @PostMapping("/postt")
    public User postt(@ApiParam("用户名") User user){
        return user;
    }
}

总结

优点

1.给一些难以理解的属性或接口增加注释信息

2.接口文档实时更新

3.可以在线测试

Swagger是一个优秀的工具，几乎所有公司都在用它

注意点

出于安全考虑和节省内存，在发布项目的时候要关闭Swagger！！！