Swagger --API框架

---

前言

---

最近开始接触公司的源码了，一些规范化的操作，让我有些陌生，不懂为什么要这样取用，比如一些注解，比如@ApiModelProperty(“模型字段类型”)，@ApiParam() @RequestBody RequestData requestData这些注解。所以今天来学习Swagge框架，慢慢的熟悉这些操作规范

一、 Swagge介绍

• 号称世界上最流行的API框架
• RetFUl Api文档在线自动生成工具 ==》Api文档与APi定义同步更新
• 直接运行，可以再接测试API接口就是（Post、Getmapping（））
• 支持多种语言：（java、php）

在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. 配置Configer

@Configuration

@EnableSwagger2            //开启Swagger2
public class SwaggerConfiger {
    
    
}

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

二、配置Swagger

Swagger的bean实例Docket,去Configuration配置

package com.hikvision.swagger.learn.configer;

/*
 * @ClassName: SwaggerConfiger
 * @Copyright(C) 2019 杭州海康威视技术有限公司
 * @Description:
 * @author tangjing13
 * @date 2021年53月21日
 */
@Configuration

@EnableSwagger2            //开启Swagger2
public class SwaggerConfiger {
    
    
      //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

      //配置Swagger信息 apiInfo
    private ApiInfo apiInfo(){
    
    
        Contact contact = new Contact("唐经13","https://blog.csdn.net/qq_36737214?spm=1000.2115.3001.5343","[email protected]");

        return new ApiInfo("唐经的Swagger日记",
                "这是描述",
                "1.0",
                "http://localhost:8080",
                contact,
                "Apache 2.0",
                "http.www.apach.org/licenses/LICENSE-2.0",
                new ArrayList<>());

    }
}

页面更改为：

配置扫描的路径

      //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                   //.basePackage指定扫描Controller包
                  //.any();扫描全部
                  // .none()都不扫描
                  // .withClassAnnotation  扫描类上的注解，包含此注解的类都被扫描
                  // .withMethodAnnotation  扫描方法上的注解   包含此注解的方法都被扫描
                .apis(RequestHandlerSelectors.basePackage("com.hikvision.swagger.learn.Controller"))
                  //过滤路径
                  // .ant(/唐经/**)  只扫描唐经下的包
                //.paths(PathSelectors.ant())
                .build();
    }

配置是否开启Swagger

    @Bean
    public Docket docket(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false) // 关闭swagger
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hikvision.swagger.learn.Controller"))
                .build();
    }

我们只希望在生产环境中使用，在发布时不使用

1、判断是否为生产环境
2、 根据是否为我们想要的环境设置enable

  @Bean
    public Docket docket(Environment environment){
    
    


            //设置要现实的Swagger环境
        Profiles profiles = Profiles.of("dev");
            //判断环境是否处在我们设置的profile的环境中
       boolean flage =  environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flage) // 关闭swagger
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hikvision.swagger.learn.Controller"))
                .build();
    }

如果关闭：

配置API文档的 不同分组

每一个docket都是一个分组，通过groupName设置环境分组的名字

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

配置实体类

1、在pojo类上增加注释

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

2、Controller层上的返回值得是我们此pojo类的实体类

    @RequestMapping("/getUser")
    public User getUser(){
    
    
        return new User();
    }

还有其他参数上的注释、都很简单、这些就不再注释了

黄金用法：在线测试

---

总结

1、通过Swagger给一些比较难理解的属性或者接口，增加注释。 2、接口文档试试更新。 3、可以在线测试（postman可以退休了）。 4、几乎所有国内大公司都在用它、每个人开发的接口在不同的文档分组中可以查看开发状况，错误。 【注意】在正式发布的时候关闭Swagger！！！！！不要让别人看到你的接口。