【Java】Swagger(文档交互)

最新推荐文章于 2024-09-25 21:23:51 发布
最新推荐文章于 2024-09-25 21:23:51 发布
阅读量2.4k 收藏 4
点赞数
文章标签： java spring boot 开发语言
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_30130205/article/details/130449173
版权

一、介绍SpringBoot集成

学习模板：

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

Swagger简介

前后端分离

Vue + SpringBoot

后端时代：前端只用管理静态页面；html由后端做。

前后端分离时代:

  • 后端：控制层、服务层、数据访问层
  • 前端：前端控制层、视图层
    • 位置后端数据，json。已经存在了，不需要后端，前端工程依旧能够跑起来
  • 前后端如何交互？通过API
  • 前后端相对独立，松耦合
  • 前后端甚至可以部署在不同的服务器上

产生一个问题：

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

解决方案：

  • 首先指定schema【计划的提纲】，实时风险更新API，降低集成的风险；
  • 早先年：指定word计划文档；
  • 前后端分离时代：
    • 前端测试后端接口：postman
    • 后端提供接口，需要实时更新最新的消息及改动！

Swagger

在项目中使用Swagger，需要导入springbox包,其中包含以下组件

  • swagger2
  • ui

SpirngBoot集成Swagger

  1. 新建springBoot web项目

  2. 寻找依赖

在这里插入图片描述

  1. 在pom.xml中导入两个依赖

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

  2. 编写一个Hello工程

    • 在主程序同级包下创建controller包，并在包里创建HelloController类

      @RestController
public class HelloController {
    
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

  3. 开启swagger

    • 在主程序同级包下创建config包，并在包里创建SwaggerConfig类

      @Configuration
@EnableSwagger2 //开启Swagger 2
public class SwaggerConfig {
    
}

  4. 测试：

    • 访问：http://localhost:8080/swagger-ui.html 效果如下

在这里插入图片描述

二、配置Swagger信息

Swagger的bean实列Docket；

编写SwaggerConfig类

@Configuration
@EnableSwagger2 //开启Swagger 2
public class SwaggerConfig {

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

    //配置Swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("吴之谦","http://wuxiuxiang.ysepan.com/","734338421@qq.com");

        return new ApiInfo(
                "我的SwaggerAPI文档",
                "这里写描述",
                "v1.0",
                "http://wuxiuxiang.ysepan.com/",
                contact,
                "Apache 2.0",
                "http://shiguiyuan.ysepan.com/",
                new ArrayList()

        );
    }

}

刷新页面，效果如下

在这里插入图片描述

三、配置扫描接口及开关

下面是swagger扫描到本项目的请求接口

在这里插入图片描述

假设我们执行扫描我们自己指定包的接口，可以在配置类中这样写

SwaggerConfig.class

@Configuration
@EnableSwagger2 //开启Swagger 2
public class SwaggerConfig {

    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //指定扫描包,RequestHandlerSelectors 配置要扫描接口的方式，这里选择的是扫描包的方式
                .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
                .build();//工程模式
    }
省略..........

可选的扫描方式：

  1. basePackage（）：扫描包
  2. any（）：扫描全部
  3. none（）：都不扫描
  4. withClassAnnotation（）：扫描类上的注解的接口
  5. withMethodAnnotation() : 扫描方法上的注解的接口

过滤扫描

SwaggerConfig的docket（）方法修改

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
                //paths（）过滤，过滤/kuang/**下面的接口
                .paths(PathSelectors.ant("/kuang/**"))
                .build();
    }

可选方式：

  1. any（）：过滤全部

  2. none（）：都不过滤

    …

Swagger启用/禁用

enable()方法的参数为true为启用，参数为false（默认）则为禁用

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
                .build();
    }

刷新页面后的效果

在这里插入图片描述

题目：我只希望Swa在生产环境中使用，在发布的时候不使用

  • 判断是否是生产环境 flag
  • 注入enable（）

先准备两份配置文件，分别为开发环境和生产环境

在这里插入图片描述

application.properties

#激活开发环境的配置文件
spring.profiles.active=dev

application-dev.properties

#设置端口号
server.port=8081

application-pro.properties

#设置端口号
server.port=8082

Swagger配置类

@Configuration
@EnableSwagger2 //开启Swagger 2
public class SwaggerConfig {

    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){
        
        //设置要显示的Swagger环境(这里比对的是dev和test，都没比对上则返回false)
        Profiles profiles = Profiles.of("dev","test");
        //判断是否处在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//开关
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
                .build();
    }
//以下配置信息省略.........

}

注意：测试的时候记得填写对应环境的端口号

四、分组和接口注释及小结

配置API文档的分组

使用groupName( )方法

    @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("狂神")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
                .build();
    }

效果如下

在这里插入图片描述

如何配置多个分组？

在swagger配置文件中配置多个实例

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

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

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


    @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("狂神")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
                .build();
    }

//以下代码省略。。。。。

实现效果:

在这里插入图片描述

实体类配置

User实体类

@ApiModel("用户实体类") //页面的标注信息
public class User {
    @ApiModelProperty("用户名") //字段的标注信息
    public String username;
    @ApiModelProperty("密码")//字段的标注信息
    public String password;
}

效果

在这里插入图片描述

controller类配置

@RestController
public class HelloController {


    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }

    @ApiOperation("Hello2请求接口")   //方法注解
    @RequestMapping("/hello")
    public String hello2(@ApiParam String username){  //参数注解
        return "hello"+username;
    }

   
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }
}
  • @ApiOperation(“Hello2请求接口”) //方法注解
  • @ApiParam //参数注解

接口测试

在这里插入图片描述

传参测试

在这里插入图片描述

测试效果

在这里插入图片描述

总结

  • 我们可以通过swagger给以下比较难理解的属性或者接口，增加注释信息
  • 接口文档实时更新
  • 可以在线测试

【注意点】

正式发布的时候，关闭Swagger！！！出于安全考虑，而且节省运行内存；

#上善若水
关注
java 配置 swagger
追随内心
09-08 371
parent>
java Swagger 配置技巧
iOS逆向与安全
04-29 1040
enableSwagger2：是springfox提供的一个注解，代表swagger2相关技术开启,会扫描当前类所在包，以及子包中所有的类型中的注解，做swagger文档的定值。spring-fox利用自身AOP特性，把swagger集成进来，底层还是Swagger，但是使用起来却方便很多，所以在实际开发中，都是直接使用spring-fox。swagger的使用: 使用swagger就是把相关信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件去更新接口文档，以及生成各端代码。
Java实战开发之swagger配置及访问
weixin_73922932的博客
03-21 1388
Swagger 是一个流行的开源框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。它可以让开发者和用户更方便地理解和使用 API。Swagger 通过定义 RESTful API 的规范（使用 YAML 或 JSON 格式）来实现这些功能。这些规范称为 OpenAPI 规范（之前称为 Swagger 规范）。Swagger 的主要特点包括：自动生成 API 文档：通过分析代码中的注解，Swagger 自动生成清晰、易读的 API 文档，包括 API 的路径、参数、响应等详细信息。
java swagger 引入和配置
zengliguang的专栏
05-12 742
文件中添加Swagger的相关依赖。请注意，Swagger的配置可能会因版本不同或具体需求而有所变化，确保查阅官方文档或最新版本的指南以获取最准确的信息。确保你的应用能够正确地映射Swagger UI的静态资源。在Spring Boot中，你可能需要在。（针对Springfox 3.0.0及以上版本）注解来启用Swagger配置。完成上述配置后，启动你的应用。Swagger UI通常可以通过。java swagger 引入和配置。（替换为你的应用端口）来访问。在你的API控制器类上使用。
Swagger 使用介绍
最新发布
世之奇伟、瑰怪，非常之观，常在于险远，而人之所罕至焉，故非有志者不能至也。
09-25 997
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(它的主要作用是：使得前后端分离开发更加方便，有利于团队协作接口的文档在线自动生成，降低后端开发人员编写接口文档的负担功能测试Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。
java插件-Swagger(快速生成接口文档)
懒洋洋的博客
03-24 1070
快速生成接口文档，懒人党的福音
❤️《微服务开发—Swagger》（建议收藏）
...
10-10 1300
Swagger 文章目录Swagger1、Swagger的作用和概念1、Swagger 的优势2、SwaggerUI 特点2、SpringBoot集成Swagger3、配置Swagger4、实体配置5、其他皮肤 1、Swagger的作用和概念 ​ 官方地址：https://swagger.io/ ​ Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务以及 集成Swagger自动生成API文档。 ​ Swagger 的目标是对 REST API 定义
java-swagger
Flying_Fish_roe的博客
01-28 1130
Swagger是一个用于设计、构建、文档化和使用RESTful Web服务的开源工具集。它允许开发人员通过Swagger规范定义API，通过Swagger UI自动生成交互式API文档，并提供一些功能强大的工具来生成客户端SDK和服务器代码。也称为OpenAPI规范，是一种用于描述和定义API的标准格式。它是一个使用JSON或YAML编写的文档，包含API的各种元数据，例如路径、参数、返回值等。Swagger UI是一个开源项目，用于生成交互式的API文档。
java应用中swagger使用
m0_56418245的博客
01-16 775
springboot中使用swagger
swagger在线文档转成word文档
09-27
Swagger是一款流行的API文档框架，常用于构建RESTful API的交互式文档。SpringBoot是Java开发者的常用框架，它简化了Spring应用的初始搭建以及开发过程。本篇文章将详细讲解如何在SpringBoot项目中利用Swagger生成的...
springboot 分布式系统swagger文档.zip
02-22
在这个名为"springboot 分布式系统swagger文档.zip"的压缩包中，我们可能找到了关于如何在Spring Boot分布式系统中集成并使用Swagger的相关资料，帮助开发者更好地管理和文档化他们的接口。 首先，让我们深入了解...
java-examples-swagger:Java示例Swagger
04-21
总结来说，Java 示例 Swagger 项目展示了如何利用 Swagger 在 Java 应用中构建可交互的 API 文档。通过学习这个例子，开发者可以更好地理解 Swagger 的工作原理，提高 API 设计的规范性和可维护性。同时，这个项目也...
Java Swagger 的相关知识讲解
Java5658的博客
06-13 356
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务以及 集成Swagger自动生成API文档。
一看就懂之Swagger神器（Java版）
qq_42429369的博客
06-02 9309
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 2.编写代码 代码如下（示例）：application.properties application-dev.properties(开发环境) application-pro.properties(生产环境) User类 Controller类 swagger配置类 马上来查看效果...
Swagger接口文档 —— 手把手教学，全方位超详细小白能看懂，百分百能用Java版
dream_ready的博客
04-18 5670
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。官网：https://swagger.io/是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
Swagger2使用及整合
fox_bert的博客
10-10 1290
一、介绍Swagger2 Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。 二、常用注解 这里是说明常用注解的含义和基本用法（也就是说已经对swagger进行集成完成） 没有集成的请参见SpringBoot集成springfox-swa...
Swagger(JAVA)
有点想法的专栏
05-09 422
文章目录1.介绍2.使用2.1 springMVC集成 1.介绍 2.使用 2.1 springMVC集成 1.添加依赖 <!--swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>sprin...
【Java】--swagger使用
寻梦友的博客
07-24 1349
介绍springboot集成swagger的方法
java swagger_java 集成swagger
weixin_27966471的博客
02-24 584
原java 集成swagger1引入jarUTF-81.81.82.7.0io.springfoxspringfox-swagger2${swagger.version}io.springfoxspringfox-swagger-ui${swagger.version}2添加配置package com.mszl.config;import org.springframework.context...
java使用swagger
07-21
在Java中使用Swagger可以通过以下步骤来实现： 1. 在你的Maven或Gradle项目中添加Swagger的依赖项。例如，对于Maven项目，可以在`pom.xml`文件中添加以下内容： ```xml <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> ``` 2. 创建一个配置类来启用Swagger。在该类上使用`@EnableSwagger2`注解，如下所示： ```java import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { } ``` 3. 创建一个API控制器类，并使用Swagger的注解来描述API接口。例如： ```java import org.springframework.web.bind.annotation.*; import io.swagger.annotations.*; @RestController @RequestMapping("/api") @Api(tags = "示例API") public class SampleController { @GetMapping("/hello") @ApiOperation("获取欢迎信息") public String hello() { return "Hello, Swagger!"; } @PostMapping("/user") @ApiOperation("创建用户") public User createUser(@RequestBody User user) { // 处理创建用户的逻辑 return user; } // 其他API接口... } ``` 4. 启动你的应用程序，并访问Swagger UI界面。Swagger UI界面默认可以通过`http://localhost:8080/swagger-ui.html`进行访问。你将能够看到由Swagger自动生成的API文档，并可以在界面上进行交互测试和调试。 请注意，上述示例中使用了Spring Boot和Springfox Swagger来演示使用Swagger的过程。你可以根据你的项目框架和需要进行相应的调整。另外，还可以通过注解来进一步定制API文档的展示效果和描述信息。 希望这些步骤能够帮助你在Java项目中成功使用Swagger！
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值