一文带你学习项目集成工具 Swagger

• Z时代
• 2024-01-10
• 分类：技术分享

项目集成工具 Swagger

1、Swagger简介

学习目标：

• 了解Swagger的概念及作用
• 掌握在项目中集成Swagger自动生成API文档

Swagger简介

前后端分离

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

产生的问题

• 前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发

解决方案

• 首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险

• 号称世界上最流行的流行框架

• RestFul Api 文档在线自动生成工具 =>Api文档与Api定义同步更新

• 直接运行，可以在线测试接口

• 支持多种语言（java、PHP等）

  官网：swagger.io/

  在项目中如何使用swagger?

  项目中使用Swagger需要spingfox

  • swagger2 jar包

  • ui jar包

    2、SpringBoot 集成Swagger

    1、新建一个springboot =web项目

    2、导入相关jar包

    <!-- 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工程

    package com.baoji.swagger.controller;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;
    @RestController
    publicclassswaggerController{
    @GetMapping("/hello")
    public String hello(){
    return"Hello！";
    }
    }
    

    4、定义配置config类(需要@Configuration和@EnableSwagger2注解)

package com.baoji.swagger.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration//定义此类为配置文件
@EnableSwagger2  //定义开启swagger2
publicclassSwaggerConfig{
}

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

3、配置Swagger

在config类中，将swagger的docter实例注入到springboot，配置界面参数信息

package com.baoji.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration//定义此类为配置文件
@EnableSwagger2  //定义开启swagger2
publicclassSwaggerConfig{
//配置了swagger的docker的bean实例
@Bean
public Docket docket(){
returnnew Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
//配置swagger信息== apiInfo
private ApiInfo apiInfo(){
//配置作者的信息
Contact contact = new Contact("张三", "https://gitee.com/Lmobject", "1042486377@qq.com");
returnnew ApiInfo(
"Lmobject的Swagger API文档",
"机会总是留给有准备的人",
"v1.0",
"https://gitee.com/Lmobject",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}

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

4、Swagger配置扫描接口

Docket.select()

//配置了swagger的docker的bean实例
@Bean
public Docket docket(){
returnnew Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors  配置要扫描的接口
//basePackage    指定要扫描的包
//any()  扫描全部
//none()  不扫描
//withClassAnnotation:  扫描类上的注解，参数是一个注解的反射对象
//withMethodAnnotation:  扫描方法上的注解
//一般选择扫描包下的接口
.apis(RequestHandlerSelectors.basePackage("com.baoji.swagger.controller"))
//paths()  过滤什么路径(一般不需要，只要扫描指定的包就行)
//.paths(PathSelectors.ant("/baoji/**"))
.build();
}

5、配置是否启动swagger

enable() //enable是否启动swagger,如果为false,表示浏览器不能访问swagger

//配置了swagger的docker的bean实例
@Bean
public Docket docket(){
returnnew Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//enable()  //enable是否启动swagger,如果为false,表示浏览器不能访问swagger
.enable(false)
.select()
//RequestHandlerSelectors  配置要扫描的接口
//basePackage    指定要扫描的包
//any()  扫描全部
//none()  不扫描
//withClassAnnotation:  扫描类上的注解，参数是一个注解的反射对象
//withMethodAnnotation:  扫描方法上的注解
//一般选择扫描包下的接口
.apis(RequestHandlerSelectors.basePackage("com.baoji.swagger.controller"))
//paths()  过滤什么路径
//.paths(PathSelectors.ant("/baoji/**"))
.build();
}

问题一： 如何让Swagger在生产环境中使用，在发布的时候不使用呢？

• 1、先判断是不是生产环境 flag=true

• 2、注入enable(flag)

  我们先来模拟配置下开发环境和发布环境

  application.properties配置文件中配置启动的环境

  spring.profiles.active=dev  #启动开发环境
  

  application-dev.properties配置开发环境的端口号

  server.port=8081
  

  application-pro.properties配置发布环境的端口号

  server.port=8082
  

  config中配置要设置显示的swagger环境、判断是否处于自己设定的环境（boolean值）、然后设置到enable中

  //配置了swagger的docker的bean实例
  @Bean
  public Docket docket(Environment environment){
  //设置要显示的swagger环境
  Profiles profiles = Profiles.of("dev","test");
  //通过environment.acceptsProfiles判断是否处在自己设定的环境中
  boolean flag = environment.acceptsProfiles(profiles);
  returnnew Docket(DocumentationType.SWAGGER_2)
  .apiInfo(apiInfo())
  //enable()  //enable是否启动swagger,如果为false,表示浏览器不能访问swagger
  .enable(flag)
  .select()
  //RequestHandlerSelectors  配置要扫描的接口
  //basePackage    指定要扫描的包
  //any()  扫描全部
  //none()  不扫描
  //withClassAnnotation:  扫描类上的注解，参数是一个注解的反射对象
  //withMethodAnnotation:  扫描方法上的注解
  //一般选择扫描包下的接口
  .apis(RequestHandlerSelectors.basePackage("com.baoji.swagger.controller"))
  //paths()  过滤什么路径
  //.paths(PathSelectors.ant("/baoji/**"))
  .build();
  }
  

  测试: http://localhost:8081/swagger-ui.html

6、配置API文档的分组

 .groupName("Lmobject")

问题三：如何配置多个分组？

多个Docket实例即可

//配置了swagger的docker的bean实例
@Bean
public Docket docket1(){
returnnew Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
returnnew Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
returnnew Docket(DocumentationType.SWAGGER_2).groupName("C");
}

7、配置实体类

实体类(3个对于API文档的注释)

package com.baoji.swagger.pojo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//@Api(注释)
@ApiModel("用户实体类")  //表示在返回的接口文档中标明此类含义
publicclassUser{
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
}

控制类（对于API文档的注释）

package com.baoji.swagger.controller;
import com.baoji.swagger.pojo.User;
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.RestController;
@Api(tags = {"Index控制器"}) // tags是对Controller的接口重新分类
@RestController
publicclassswaggerController{
//Operation 接口，用于放在方法上
@ApiOperation("Hello控制类") //用于描述接口的注释
@GetMapping("/hello")
public String hello(@ApiParam("用户名") String name){
return"Hello！"+name;
}
//只要我们的接口中,返回值存在实体类，它就会扫描到swaager中
@GetMapping("/user")
public User user(){
returnnew User();
}
@PostMapping("/postTest")
public User postTest(@ApiParam("用户实体类") User user){
return user;
}
}

8、测试功能

在对应的接口中点击Try it out

Excute 开始执行接口方法，完成之后，后面有对应的返回响应码

9、总结

1、我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息

2、接口文档实时更新

3、可以在线测试

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

「注意点」在正式发布的额时候，关闭Swagger！！！出于安全考虑，而且节省运行的内存；

以上是 一文带你学习项目集成工具 Swagger 的全部内容， 来源链接： utcz.com/a/29864.html