Swagger 3.0与SpringBoot 2.6.1集成

世界上最流行的Api框架
RestFul Api文档在线自动生成工具=>Api文档与Api定义同步更新
直接运行，可以在线测试Api接口(controller（RequestMapping）)
Swagger官网https://swagger.io/

1. 在项目中使用Swagger需要导入jar包

springBox-swagger2
springBox-swagger ui

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

2. 编写一个Controller

@RestController
public class HelloController {

    // /error默认请求
    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}

主启动类需添加@EnableOpenApi注解

@EnableOpenApi
@SpringBootApplication
public class Springboot09SwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run (Springboot09SwaggerApplication.class, args);
    }

}

3. 配置SwaggerConfig

@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig{
//RequestHandlerSelectors)配置扫描接口的方式
    /*RequestHandlerSelectors.basePackage("com.ji.controller"):指定扫描的包
      RequestHandlerSelectors.any() 扫描全部
      RequestHandlerSelectors.none() 不扫描
      RequestHandlerSelectors.withClassAnnotation(RestController.class) 扫描类上的注解    @Target(ElementType.TYPE)
      RequestHandlerSelectors.withMethodAnnotation (GetMapping.class) 扫描方法上的注解  @Target(ElementType.METHOD)
    * */

    //paths :过滤什么路径
    //配置SwaggerDocket Bean实例

    //配置
    @Bean
    public Docket docket(Environment environment){
        //多环境 开关swagger  environment
        //设置要显示swagger 的环境
        Profiles profiles=Profiles.of ("dev","test");
        //判断当前环境是否是profiles中显示swagger的环境
        boolean b = environment.acceptsProfiles (profiles);


        return new Docket (DocumentationType.SWAGGER_2)
                .apiInfo (apiInfo ())
                .groupName ("jsp")   //配置Api文档分组   多个Docket分组
                .enable (b)   //是否启动swagger 如果为false则swagger不能再浏览器中访问
                .select ()
                .apis (RequestHandlerSelectors.basePackage("com.ji.controller"))
                .paths (PathSelectors.ant ("/ji/**"))
                .build ();
    }
    @Bean
    public Docket docket1(){
        return new Docket (DocumentationType.SWAGGER_2)
                .apiInfo (apiInfo ())
                .groupName ("hcy");   //配置Api文档分组
    }
    @Bean
    public Docket docket2(){
        return new Docket (DocumentationType.SWAGGER_2)
                .apiInfo (apiInfo ())
                .groupName ("zzz");   //配置Api文档分组
    }
    //配置swagger信息
    private ApiInfo apiInfo(){
        return new ApiInfo ("Jsp SwaggerLogger",
                "学习",
                "17.0",
                "https://www.cnblogs.com/Liuyunsan/",
                new Contact ("jsp", "https://www.cnblogs.com/Liuyunsan/", "[e-mail]"),   //作者信息
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList ());
    }
}

4. Models

@RestController
public class HelloController {
    //Operation接口  给controller 方法增加注释
    @ApiOperation ("helloController控制类")
    // /error默认请求
    @GetMapping(value = "/ji/hello")
    public String hello(){
        return "hello";
    }

    @PostMapping(value = "/ji/hello")
    //只要我们的接口中，返回值张存在实体类，它就会被扫描到swagger中
    public User user(@ApiParam("用户名") String username){
        return new User();
    }


}

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

5. 总结

• 可以通过Swagger给比较难理解的属性或者接口，增加注释信息
• 接口文档实时更新
• 可以在线测试
• 正式发布时，需要关闭Swagger（出于安全考虑和性能考虑）