Swagger3.0介绍及springboot整合Swagger3.0

Swagger

学习目标:

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

一、Swagger出现的原因

前后端分离
Vue+SpringBoot
后端时代:前端只用管理静态页面;html==>后端。模板引擎 JSP=>后端是主力

前后端分离时代:

  • 后端:后端控制层,服务层,数据访问层 【后端团队】
  • 前端:前端控制层,视图层 【前端团队】
    • 伪造后端数据,json。已经存在了,不需要后端,前端工程依|旧能够跑起来·前端后如何交互?===>API
  • 前后端相对独立,松耦合;
  • 前后端甚至可以部署在不同的服务器上;

产生一个问题:

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

解决方案

  • 首先指定schema[计划的提纲],实时更新最新API,降低集成的风险;
  • 早些年:指定word计划文档;
    -前后端分离:

前后端分离:

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

二、Swagger介绍

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

官网:https://swagger.io/

1、springfox-swagger 2

SpringBoot项目整合swagger2需要用到两个依赖:springfox-swagger2和springfox-swagger-ui,用于自动生成swagger文档。

  • springfox-swagger2:这个组件的功能用于帮助我们自动生成描述API的json文件
  • springfox-swagger-ui:就是将描述API的json文件解析出来,用一种更友好的方式呈现出来。

2、SpringFox 3.0.0 发布

此版本的亮点:

  • Spring5,Webflux支持(仅支持请求映射,尚不支持功能端点)。
  • Spring Integration支持。
  • SpringBoot支持springfox Boot starter依赖性(零配置、自动配置支持)。
  • 支持OpenApi 3.0.3。
  • 零依赖。几乎只需要spring-plugin,swagger-core ,现有的swagger2注释将继续工作并丰富openapi3.0规范。

兼容性说明:

  • 需要Java 8
  • 需要Spring5.x(未在早期版本中测试)
  • 需要SpringBoot 2.2+(未在早期版本中测试)

注意:Swagger2.0Swagger3.0有很多区别,下面使用的是Swagger3.0,有区别的地方会简单说明

三、SpringBoot集成Swagger

1、创建springboot WEB项目

项目设置
在这里插入图片描述
选择web模块
在这里插入图片描述

2、导入相关依赖

swagger3.0以下版本导入这两个就可以了

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</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>

swagger3.0以上还需要导入,不然无法进入后台界面

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

3、编写万能的Hello工程

创建Controller层写一个HelloController
写一个测试路径hello进行测试,项目是否可以跑起来。
在这里插入图片描述
测试地址:http://localhost:8080/
出现下面页面就成功了!
在这里插入图片描述
继续学习吧!!!

4、配置Swagger

创建config层编写Swagger配置
在这里插入图片描述

package com.zhao.swagger.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
}

5、测试运行

运行程序进行测试
注意:版本不同测试路径不同

  • Swagger3.0——>测试地址:http://localhost:8080/swagger-ui/index.html
  • Swagger2.0——>测试地址:http://localhost:8080/swagger-ui.html

显示的页面一共分四个部分如下图:
在这里插入图片描述

四、配置Swagger

Swagger的bean实例Docket;

1、创建配置类配置Swagger

注意:版本不同注解不同

  • Swagger3.0——>注解:@EnableOpenApi
  • Swagger2.0——>注解:@EnableSwagger2
    在这里插入图片描述
package com.zhao.swagger.config;

        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import springfox.documentation.oas.annotations.EnableOpenApi;
        import springfox.documentation.spi.DocumentationType;
        import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi //开启Swagger3.0
public class SwaggerConfig {

    //配置swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30);
    }
}

2、分析源码找参数DocumentationType.OAS_30

在这里插入图片描述

这里需要的是一个DocumentationType类型的参数
在这里插入图片描述

我们看一下Docket源码,找到DocumentationType去看他的源码
在这里插入图片描述
这里找到了我们需要的参数,选择我们使用的即可
在这里插入图片描述

3、配置Swagger信息ApiInfo

我们去看ApiInfo的源码获取我们需要的信息
在这里插入图片描述
配置代码如下(他们对应的信息后面有解释)

 //配置Swagger信息apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact= new Contact(
                "Mr.zhao",
                "https://blog.csdn.net/qq_43521797?spm=1011.2124.3001.5343",
                "1433304356@qq.com");
        return new ApiInfo(
                "Mr.zhao API文档",
                "再小灰尘也能在阳光下起舞",
                "v1.0",
                "https://blog.csdn.net/qq_43521797?spm=1011.2124.3001.5343",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }

配置的信息分析如图:
在这里插入图片描述

五、配置扫描接口及开关

分析一下接口部分显示信息
在这里插入图片描述
信息来自于springfox-swagger-ui-3.0.0.jar
在这里插入图片描述

1、设置扫描包及过滤

Docket下的select()

  //配置swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors配置要扫播接口的方式
                //basePackage指定要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.zhao.swagger.controller"))
                //paths()过滤什么路径
                .paths(PathSelectors.ant("/zhao/**"))
                .build();
    }
1)RequestHandlerSelectors扫描接口的方式

RequestHandlerSelectors,扫描接口的方式。我们去RequestHandlerSelectors的源码看看其他配置方法

  • basePackage指定要扫描的包
  • any();扫描全部
  • none;不扫描
  • withClassAnnotation 扫描类上得注解
  • withMethodAnnotation 扫描方法上得注解
    在这里插入图片描述
    在这里插入图片描述
2)PathSelectors过滤方式

和上面一样我们去源码中看他的方法有哪些

  • ant():过滤路径
  • any():全部过滤
  • none():不过滤
  • regex():正则表达式

我们使用第一种过滤路径测试
在这里插入图片描述

过滤后什么都没有了
在这里插入图片描述

2、设置Swagger启动与关闭

我们在Docket的源码中科院看到enabled=true这个属性就是控制启动
在这里插入图片描述
我们去改变一下他的值 改成false关闭一下试试
注意:下面红框的是一个整体不能在吗中间添加其他东西。
在这里插入图片描述

我们在.apiInfo(apiInfo())后面进行添加.enable(false)

 @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .enable(false)//关闭Swagger
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhao.swagger.controller"))
                .build();
    }

测试地址:http://localhost:8080/swagger-ui/index.html#/
关闭后的效果
在这里插入图片描述

3、设置Swagger在对应的项目环境启动

我们在项目中只在开发环境开启Swagger,生产环境就要关闭Swagger。
下面我们进行设置一下

1)创建测试环境
  • application-dev:开发环境
  • application-pro:生产环境
    在这里插入图片描述
    application.properties内代码:spring.profiles.active=dev
    application-dev.properties内代码:server.port=8081
    application-pro.properties内代码:server.port=8082
2)编写配置类获取项目环境

Profiles.of()设置要显示的swagger的环境
通过environment.acceptsProfiles判断是否处在自己设定的环境中 获取booleanflag
赋值给enable(flag)

    //配置swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的swagger的环境
        Profiles profiles =Profiles.of("dev");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zhao.swagger.controller"))
                .build();
    }

3)测试

我们先测试dev环境
application.properties中切换环境为dev环境: spring.profiles.active=dev

dev环境===》测试地址:http://localhost:8081/swagger-ui/index.html#/
在这里插入图片描述

这次测试pro环境
application.properties中切换环境为pro环境: spring.profiles.active=pro

pro环境===》测试地址:http://localhost:8082/swagger-ui/index.html#/
在这里插入图片描述

六、分组

1、设置分组

我继续看Docket的源码我们可以看到分组的默认值为default
在这里插入图片描述
下面我们进行修改,指需要一行代码

 .groupName("Mr.zhao")

在这里插入图片描述
在这里插入图片描述

2、多个分组

多个分组就是多人协作开发时每个人分组
其实就是多个Docket实例
下面我们测试一下
我们在复制几个Docket实例进行测试

@Bean
    public Docket docket1(Environment environment){
        return new Docket(DocumentationType.OAS_30).groupName("A");
    }
    @Bean
    public Docket docket2(Environment environment){
        return new Docket(DocumentationType.OAS_30).groupName("B");
    }
    @Bean
    public Docket docket3(Environment environment){
        return new Docket(DocumentationType.OAS_30).groupName("C");
    }

运行一下就可以看到多个分组了,选择一个分组信息就会发生变化,以及测试路径。

在这里插入图片描述

七、接口注释及实体类注释

1、接口注释

接口常用的三个注解

  • @Api(tags = "helloController层"):放在控制层类上,描述控制层
  • @ApiOperation(value = "hello2方法",notes = "方法描述"):放在方法控制层上,描述控制层方法
  • @ApiParam("用户名"):参数描述
package com.zhao.swagger.controller;

import io.swagger.annotations.Api;
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 = "helloController层")
@RestController
public class HelloController {

    @ApiOperation("hello方法")
    @PostMapping("/hello")
    public String hello(){
        return "hello Swagger";
    }
    @ApiOperation(value = "hello2方法",notes = "方法描述")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return username;
    }
}

在这里插入图片描述

2、实体类注释

我们先创建pojo编写一个User进行测试

package com.zhao.swagger.pojo;

public class User {
    private String username;
    private String password;
}

我们直接启动项目看看可以扫描我们的实体类吗?答案是不能
在这里插入图片描述
方法一(不是用注解,也可以扫描到实体类)
实体类不使用注释也可以被扫描,只要请求返回类型是实体类即可。我们测试一下
我写一个方法

@ApiOperation(value = "user方法",notes = "测试不使用注解,把实体类作为返回值可以扫描到实体类吗")
    @GetMapping("/user")
    public User user(){
        return new User();
    }

实体有了但是这样的没有属性,这是因为没有给属性添加get set方法,
在这里插入图片描述
给是实体类添加get set 方法,再次测试

package com.zhao.swagger.pojo;

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

public class User {
    private String username;
    private String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

这次就完美了
在这里插入图片描述

方法二(注解)

  • @ApiModel("用户实体类"):用于实体类上,描述实体类
  • @ApiModelProperty(value = "用户名",hidden = false):用于属性上描述实体类属性,hidden功能是,是否隐藏该属性
package com.zhao.swagger.pojo;

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

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty(value = "用户名",hidden = false)//hidden是否隐藏
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", password='" + password + '\'' +
                '}';
    }
}

在这里插入图片描述

八、简单的测试

在这里插入图片描述

### 回答1: 首先,需要在 `pom.xml` 文件中添加以下依赖: ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` 接着,在 Spring Boot 的启动类上添加 `@EnableSwagger2WebFlux` 注解: ```java import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import springfox.documentation.swagger2.annotations.EnableSwagger2WebFlux; @SpringBootApplication @EnableSwagger2WebFlux public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } } ``` 最后,在你的控制器类上添加 `@Api` 和 `@ApiOperation` 注解进行 API 文档的描述: ```java import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/hello") @Api(tags = "HelloController", description = "示例控制器") public class HelloController { @GetMapping("/") @ApiOperation(value = "hello", notes = "示例接口") public String hello() { return "Hello, Swagger!"; } } ``` 然后,启动应用程序并访问 `http://localhost:<port>/swagger-ui/index.html` 即可查看生成的 API 文档。 ### 回答2: Spring Boot整合Springfox Swagger 3.0 Springfox Swagger是一个用于为Spring Boot应用程序生成文档的框架。在Spring Boot中使用Springfox Swagger 3.0,可以方便地为API生成可视化的接口文档,并提供简化的API调试和测试功能。下面是整合Springfox Swagger 3.0的步骤: 首先,需要在Spring Boot项目的pom.xml文件中添加Springfox Swagger 3.0的依赖: ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` 然后,在Spring Boot应用程序的启动类上添加`@EnableOpenApi`注解,以启用Springfox Swagger 3.0的功能: ```java @SpringBootApplication @EnableOpenApi public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } } ``` 接下来,需要在项目中添加一个配置类,其中配置Swagger的相关信息: ```java @Configuration public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.OAS_30) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); } } ``` 上述配置中,通过`apis`方法指定需要生成文档的Controller所在的包,通过`paths`方法指定需要生成文档的接口路径。可以根据需要进行自定义配置。 最后,在浏览器中访问http://localhost:8080/swagger-ui/index.html,可以看到生成的接口文档页面。在该页面上,可以查看API的详细信息,进行测试和调试。 整合Springfox Swagger 3.0是一个方便快捷的方式来创建和管理API文档。它提供了友好的UI界面和强大的功能,可以大大简化API文档的维护工作,并提高团队合作效率。 ### 回答3: Spring Boot整合Springfox Swagger 3.0的步骤如下: 1. 添加相关依赖:在`pom.xml`文件中添加以下依赖: ```xml <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` 2. 创建Swagger配置类:创建一个配置类,并使用`@Configuration`注解进行标记。在该类中,可以配置Swagger的相关信息,如标题、描述、版本等。 ```java @Configuration @EnableSwagger2 //启用Swagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API文档标题") .description("API文档描述") .version("1.0.0") .build(); } } ``` 3. 配置Swagger的URL路径:在`application.properties`或`application.yml`文件中,添加以下配置项,指定Swagger的URL路径: ```yaml springfox.documentation.swagger-ui.path=/swagger-ui.html ``` 4. 启动项目:启动Spring Boot项目,访问http://localhost:8080/swagger-ui.html,即可查看生成的API文档。 以上是Spring Boot整合Springfox Swagger 3.0的基本步骤,通过配置Swagger相关信息,可以实现自动生成API文档,并提供可视化的界面。
评论 8
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值