526互联

Swagger

发布时间 2023-07-28 16:11:30作者: 吾执青剑向天涯

SWAGGER

学习的目标

  • 了解swagger的作用
  • 了解前面后端分离
  • 在springboot中集成swagger

swagger简介

前后端分离

vue + springboot

后端时代:

​ 前端只有静态页面;html==>后端

​ 模版引擎 jsp=>后端是主力

前后端分离时代

  • 后端 : 后端控制层,服务层,数据访问层[后端团队]
  • 前端 : 前端控制层,视图层[前端团队]
    • 伪造后端数据,json 已经存在,不需要后端就可以启动起来
  • 前后端如何交互?==>接口
  • 前后端相互独立,松耦合;
  • 前后端甚至可以部署在不同的服务器

产生一个问题:

  • 前端集成调用,前端人员和后端人员无法做到“及时协商,尽早解决” ,最终导致问题集中爆发;

解决方案

  • 首先制定schema[计划的提纲],实时更新最新的API,降低集成的风险;
  • 早些年:指定word计划文档;
  • 前后端分离
    • 前端测试后端接口:postman
    • 后端提供接口,需要实时更新的消息及改动

swagger

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

官网招摇文档 (swagger.io)

在项目中使用swagger 需要 springbox;

  • swagger2
  • swaggerUI

springBoot 集成Swagger

  1. 新建一个springBoot web项目

  2. 导入相关依赖

    
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>


<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

  3. 编写一个helloworld 测试是否成功启动

  4. 配置swagger ==>config文件

    @Configuration
@EnableSwagger2//启用Swagger2
public class SwaggerConfig {

}

    # 出现一个错误  无法启动项目
# org.springframework.context.ApplicationContextException: Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException
# at ……
# Caused by: java.lang.NullPointerException: null
# at ……
# … 14 common frames omitted

# 错误原因：SpringBoot2.6.x使用PathPatternMatcher匹配路径，Swagger引用的Springfox基于AntPathMatcher匹配路径。匹配方式不同，导致错误。

# 解决思路：将SpringBoot的匹配路径方式更改为AntPathMatcher，两者相同即可。添加配置信息如下：

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

    可见的网站 Swagger UI

  5. 是

Swagger 配置扫描接口

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 是否启动swagger
                .enable(true)
                .select()
                // RequestHandlerSelectors
                // basePackage指定要扫描的包
                // none()不扫描
                // any()全部扫描
                // withClassAnnotation() 扫描类上的注解
                // withMethodAnnotation()   扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.lmq.controller"))
                //过滤
//                .paths(PathSelectors.ant("/lmq/**"))
                .build();

配置API文件分组

配置groupname

package com.lmq.config;

import org.springframework.boot.SpringBootConfiguration;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;


/**
 * @author 羡鱼
 * @version 1.0
 * @date 2023/7/26 17:22
 */
@Configuration  // 配置到spring配置里面
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docker2(Environment environment) {
        // 设置要显示的swagger 环境
        Profiles dev = Profiles.of("dev", "test");
        // 获取项目环境  判断是否处于自己设定的环境当中
        boolean b = environment.acceptsProfiles(dev);
        return new Docket(DocumentationType.SWAGGER_2).groupName("docker2")
                .apiInfo(apiInfo())
                .enable(b);
    }

    @Bean
    public Docket docker3(Environment environment) {
        // 设置要显示的swagger 环境
        Profiles dev = Profiles.of("dev", "test");
        // 获取项目环境  判断是否处于自己设定的环境当中
        boolean b = environment.acceptsProfiles(dev);
        return new Docket(DocumentationType.SWAGGER_2).groupName("docker3")
                .apiInfo(apiInfo())
                .enable(b);
    }

    @Bean
    public Docket docker(Environment environment) {
        // 设置要显示的swagger 环境
        Profiles dev = Profiles.of("dev", "test");
        // 获取项目环境  判断是否处于自己设定的环境当中
        boolean b = environment.acceptsProfiles(dev);

        return new Docket(DocumentationType.SWAGGER_2).groupName("lmq")
                .apiInfo(apiInfo())
                // 是否启动swagger
                .enable(b)

                .select()
                // RequestHandlerSelectors
                // basePackage指定要扫描的包
                // none()不扫描
                // any()全部扫描
                // withClassAnnotation() 扫描类上的注解
                // withMethodAnnotation()   扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.lmq.controller"))
                //过滤
//                .paths(PathSelectors.ant("/lmq/**"))
                .build();
    }

    // 配置swagger 信息=apiInfo
//    @ConfigurationProperties(prefix = "api-info")
    private ApiInfo apiInfo() {
        // 作者信息
        Contact DEFAULT_CONTACT = new Contact("羡鱼", "http://xn--4t0ay40d.fun/", "1435456124@qq.com");

        return new ApiInfo("羡鱼的文档"
                , "学习 学习 学习"
                , "v1.0"
                , "http://xn--4t0ay40d.fun/"
                , DEFAULT_CONTACT
                , "Apache 2.0"
                , "http://www.apache.org/licenses/LICENSE-2.0"
                , new ArrayList<>());
    }

}

实体类

package com.lmq.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @author 羡鱼
 * @version 1.0
 * @date 2023/7/26 18:57
 */
//@Api("用户实体类")
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String pwd;

    public User(String username, String pwd) {
        this.username = username;
        this.pwd = pwd;
    }
}

可以在网页测试接口,几乎部分大公司都有使用

注意在正式发布的时候关闭!!!! 安全考虑 节省内存