Swagger

2022/8/30 23:52:59

本文主要是介绍Swagger,对大家解决编程问题具有一定的参考价值,需要的程序猿们随着小编来一起学习吧!

Swagger

学习目标:

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

1、Swagger简介

前后端分离

Vue+SpringBoot

后端时代:前端只用管理静态页面html>后端。模版引擎JSP>后端是主力

前后端分离时代:

  • 后端:后端控制层,服务层,数据访问层
  • 前端:前端控制层,视图层
  • 前后端如何交互?==>API
  • 前后端相对独立,松耦合;
  • 前后端甚至可以部署在不同的服务器中

产生一个问题:

  • 前后端集成联调,前端人员和后端人员无法做到,及时协商,尽早解决

解决方案:

  • 首先指定schema【(计划或理论的)提要,纲要】,实时更新最新API,降低集成的风险

  • 早些年:指定word计划文档

  • 前后端分离:

    • 前端测试后端接口:postman
    • 后端提供接口,需要实时更新最新的消息及改动

2、Swagger

  • 号称世界上最流行的API框架
  • RestFul API文档在线自动生成工具==>API文档与API定义同步更新
  • 直接运行,可以在线测试API接口;
  • 支持多种语言:(Java,PHP)

官网https://swagger.io

在项目使用Swagger需要springfox;

  • swager2
  • swagerUI

3、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>
    

    如果版本不匹配,在yaml中配置

    spring:
      mvc:
       pathmatch:
        matching-strategy: ant_path_matcher
    
  3. 编写一个hello工程

  4. 配置Swagger的Config

    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
    }
    

    image

4、配置Swagger

Swagger的bean实例Docket

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置了Swagger的docket的bean实例
    @Bean
    public Docket docket(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置Swagger信息Info
    private ApiInfo apiInfo(){
        Contact contact = new Contact("XS","http://localhost:8080/swagger-ui.html#/","x1270059552@163.com");
        return new ApiInfo(
                "XS的测试API文档",
                "Api Documentation",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

5、Swagger配置扫描接口

Docket.select()

  • RequestHandlerSelectors,配置要扫描的接口方式
  • basePackage:指定要扫描的包
  • any():扫面全部
  • none():不扫描
  • withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
  • withMethodAnnotation:扫描方法上的注解
//配置了Swagger的docket的bean实例
@Bean
public Docket docket(){
    return  new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors,配置要扫描的接口方式
            //basePackage:指定要扫描的包
            //any():扫面全部
            //none():不扫描
            //withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
            //withMethodAnnotation:扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.controller"))
            //选择路径扫描,
            // .paths(PathSelectors.ant(""))
            .build();
}

Docket.enable

是否启动swagger

   //配置了Swagger的docket的bean实例
    @Bean
    public Docket docket(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)//不启动
    }

根据开发环境配置是否启动swager

如在测试环境中

spring:
  mvc:
   pathmatch:
    matching-strategy: ant_path_matcher
  profiles:
    active: dev
@Bean
public Docket docket(Environment environment){

    //设置要显示的swagger环境
    Profiles profiles = Profiles.of("dev");

    //获取项目的环境,通过environment.acceptsProfiles判断是否处在自己设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);
    return  new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(flag)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.controller"))
            .build();
}

配置API文档的分组

Docket.groupName

配置多个分组就创建多个Docket对象

配置实体类

@Data
@AllArgsConstructor
@NoArgsConstructor
//@api()注释
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名属性")
    private String username;
    @ApiModelProperty("密码属性")
    private String password;
}

重写controller

@RestController
public class HelloController {
    @GetMapping(value = "/hello")
    public String hello(){
        return "hello";
    }

    //只要我们的接口中,返回值存在实体类,它就会被扫描到swagger中
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }
    //Operation接口
    @GetMapping("hello2")
    @ApiOperation("Hello控制类")
    public String hello(@ApiParam("用户名") String username){
        return  "hello"+username;
    }
}

image

6、总结:

  1. 我们可以通过Swagger给一些比较难理解的属性或者接口,增加注释信息
  2. 接口文档实时更新
  3. 可以在线测试

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

【注意点】在正式发布的时候,注意关闭Swagger



这篇关于Swagger的文章就介绍到这儿,希望我们推荐的文章对大家有所帮助,也希望大家多多支持为之网!


扫一扫关注最新编程教程