超简单的Swagger快速入门

最新推荐文章于 2022-10-19 12:26:32 发布
最新推荐文章于 2022-10-19 12:26:32 发布
阅读量1.3k 收藏 9
点赞数 3
分类专栏： 常用工具 文章标签： java spring boot web
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_29051413/article/details/106481940
版权

文章目录

1、简介

1.1 前后端分离

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

1.2 存在的问题

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

1.3 解决方案

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

1.4 Swagger

  号称世界上最流行的API框架；
  Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新；
  直接运行，在线测试API；
  支持多种语言 （如：Java，PHP等）；
  官网：https://swagger.io/

2、SpringBoot集成Swagger

2.1 前提

  jdk>=1.8，否则swagger2无法运行。

2.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>

2.3 Swagger配置类

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}

2.4 测试

  创建一个HelloController：

@Controller
@RequestMapping("/test")
public class HelloController {

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

  浏览器输入：http://localhost:8080/swagger-ui.html
  可以看到swagger的界面：
在这里插入图片描述

3、Swagger的配置

  Swagger的配置全部在配置类上。

3.1 Docket

  Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
		return new Docket(DocumentationType.SWAGGER_2);
	}
}

3.2 配置文档信息

  可以通过apiInfo()属性配置文档信息：

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()); // 配置文档信息
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("Meumax", "https://blog.csdn.net/qq_29051413", "578541632@qq.com");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

  配置后的效果：
在这里插入图片描述

3.3 配置扫描接口

  构建Docket时通过select()方法配置怎么扫描接口：

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) // 配置文档信息
                .select()   // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("pers.klb.springswagger.controller"))
                .build();
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("Meumax", "https://blog.csdn.net/qq_29051413", "578541632@qq.com");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

3.3.1 select()

  select()方法源码定义如下：

public class Docket implements DocumentationPlugin {
	// ...
	public ApiSelectorBuilder select() {
	    return new ApiSelectorBuilder(this);
	}
	// ...
}

  和Docket的其他方法不同，select()方法返回的是一个Builder，也就说调用了这个方法后就不能继续链式调用Docket的其他方法了。
  select()方法的作用是为API选择器初始化一个ApiSelectorBuilder，使得后面可以调用apis、paths等方法，最后使用build方法返回一个Docket。
  如果觉得看不太明白，可以看源码。

3.3.2 apis(Predicate selector)

  用于配置API接口的扫描范围：

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo() 
                .select()   
				// 去配置扫描接口,RequestHandlerSelectors配置如何扫描接口	              	
              	.apis(RequestHandlerSelectors.basePackage("pers.klb.springswagger.controller")) 
                .build();
    }
    
}

  RequestHandlerSelectors是Predicate<RequestHandler>的一个实现类，RequestHandlerSelectors的常用方法有：
  1、any()：扫描所有，项目中的所有接口都会被扫描到；
  2、none()：不扫描任何接口；
  3、withMethodAnnotation()：通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求；
  4、withClassAnnotation：通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口；
  5、basePackage()：根据包路径扫描接口。

3.3.3 path(Predicate selector)

  apis()方法的返回值为this，也就是说可以回调。
  ApiSelectorBuilder除了apis()还有一个paths()，可以配置接口扫描过滤：

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("pers.klb.springswagger.controller"))
       // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
      .paths(PathSelectors.ant("/user/**"))
      .build();
}

  PathSelectors是Predicate<String>的一个实现类，常用方法有：
  1、any()：任何请求都扫描；
  2、none()：任何请求都不扫描；
  3、regex(final String pathRegex)：通过正则表达式控制；
  4、ant(final String antPattern)：通过ant()控制只扫描请求以"/**"开头的接口,也就是控制器里面的访问路径。

3.4 配置Swagger开关

  Docket有一个enabled属性，用于控制是否开启Swagger。
  一般来说，我们在开发和测试环境会开启Swagger，在生产环境不会开启。那我们怎么实现这个功能呢？
  1、配置判断条件

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {

    @Bean
    public Docket docket(Environment environment) {
        // 设置要显示swagger的环境
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是否处于该环境
        // 通过 enable() 接收此参数判断是否要显示
        boolean b = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("pers.klb.springswagger.controller"))
                // 配置如何通过path过滤,即这里只扫描请求以/hello开头的接口
                .paths(PathSelectors.ant("/hello/**"))
                .build();
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("Meumax", "https://blog.csdn.net/qq_29051413", "578541632@qq.com");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }
}

  2、如果配置文件的开发环境设置为生产模式：
  application.properties：

spring.profiles.active=prod

  3、启动工程，浏览器输入：http://localhost:8080/swagger-ui.html#/，可以看到：
在这里插入图片描述
  4、配置文件改为开发环境：
  application.properties：

spring.profiles.active=dev

  浏览器访问又可以了：
在这里插入图片描述

3.5 配置API分组

  当然了，我Swagger不可能是一个人用的，是团队开发的，如果有五个人，每个人都会产生一个API页面。我们只需要在Docket设置groupName("klb")即可给自己开发的API命名。
  比如，现在有ABC三个程序员，那么我就定义三个Docket：

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

  打开Swagger页面，我们就可以看到分组效果：
在这里插入图片描述

4、实体配置

  如果要在Swagger页面的Models上看到我们的实体类，API接口的返回值就必须包含实体类，比如我有一个User实体类：

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

  然后控制器的接口必须有返回这个User的：

@Controller
@RequestMapping("/test")
public class HelloController {

    @PostMapping("/user")
    public User user(){
        return new User();
    }

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

  查看Swagger页面：
在这里插入图片描述

5、常用注解

  讲了这么多，现在Swagger页面上显示的结果，前端看到表示想打人，为什么呢，因为毫无说明，于是Swagger提供了一系列的注解来让我们在这些API接口和实体类上面标明注释信息。
  Swagger的所有注解定义在io.swagger.annotations包下。

@ApiModel

  作用是给类添加注释信息：

@ApiModel("User实体类")
public class User {
    public  String username;
    public  String password;
}

  效果为：
在这里插入图片描述

@ApiModelProperty

  作用是给类的属性写注释信息：

@ApiModel("User实体类")
public class User {
    @ApiModelProperty("用户名")
    public  String username;

    @ApiModelProperty("密码")
    public  String password;
}

  效果为：
在这里插入图片描述

@Api()

  作用在类上，表示标识这个类是swagger的资源，一般是模块：

@Api(value = "⽤户博客", tags = "博客接⼝")
@Controller
@RequestMapping("/test")
public class HelloController {
	// ...
}

  效果如下：
在这里插入图片描述

@ApiOperation()

  ⽤于⽅法； 表示⼀个http请求的操作：

@Controller
@RequestMapping("/test")
public class HelloController {

    @GetMapping("/detail")
    @ApiOperation(value = "获取⽤户信息", notes = "传⼊notice" , position = 2)
    public User detail(Integer id) {
        return new User();
    }
}

  效果如下：
在这里插入图片描述

@ApiParam()

  ⽤于⽅法，参数，字段说明； 表示对参数的添加元数据（说明或是否必填等）。

@ApiIgnore()

  ⽤于类，⽅法，⽅法参数 表示这个⽅法或者类被忽略；

@ApiImplicitParam()

  ⽤于⽅法，表示单独的请求参数；

@ApiImplicitParams()

  ⽤于⽅法，包含多个 @ApiImplicitParam。

小结

  我们也可以给请求的接口配置一些注释：

@Api(value = "⽤户博客", tags = "博客接⼝")
@Controller
@RequestMapping("/test")
public class HelloController {

    @ApiOperation("klb")
    @PostMapping("/klb")
    @ResponseBody
    public String kuang(@ApiParam("这个名字会被返回")String username){
        return username;
    }

  效果如下：
在这里插入图片描述

6、换皮肤

6.1 自带皮肤

  我们可以导入不同的包实现不同的皮肤定义，默认情况下，我们导入的依赖是：

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

  访问路径是：http://localhost:8080/swagger-ui.html

6.2 换成bootstrap

  依赖改为:

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

  访问路径是：http://localhost:8080/doc.html
  效果为:
在这里插入图片描述

6.3 换成Layui-ui

  依赖改为：

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

  访问路径：http://localhost:8080/docs.html

6.4 换成mg-ui

  依赖改为:

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

  访问路径：http://localhost:8080/document.html

学哥斌
关注
  • 3
    点赞
  • 踩
  • 9
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
Swagger简单介绍
weixin_42408447的博客
05-22 1317
一.一句话介绍 Swagger Swagger是一个接口文档生成工具，同时提供接口测试调用的辅助功能。 二.关于 Swagger Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因： （1）mSwagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。 （2）Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。 （3）Swagger 文件可以在许多不同的平台上从代码注释中自动生成。 （4）Swagger 有一个强大的社区，里面有许
【SpringBoot】swagger 快速上手的两种使用方法
瑞新の博客：bennyrhys
11-11 3248
一：swagger是什么？ 1、是一款让你更好的书写API文档的规范且完整框架。 2、提供描述、生产、消费和可视化RESTful Web Service。 3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。 二：使用 方法一：使用第三方依赖（最简单的方法） 1、在pom.xml文件中添加第三方swagger依赖（） <dependency> <groupId>com.spring4all</groupId>
在 Spring Boot 项目中使用 Swagger 文档
三分恶的博客
11-02 1154
Spring Boot 框架是目前非常流行的微服务框架，我们很多情况下使用它来提供 Rest API。而对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证 API 文档的及时性将有很大的帮助。本文将使用 Swagger 2 规范的 Springfox 实现来了展示如何在 Spring Boot 项目中使用 Swagger，主要包含了如何使用 Swagger 自动生成文档、使用 Swagger 文档以及 Swagger 相关
SpringBoot-----集成Swagger
qq_44236958的博客
04-18 745
SpringBoot集成Swagger 文章目录SpringBoot集成Swagger前后端分离:产生的问题:SwaggerSpringBoot集成Swagger配置Swagger配置扫描接口配置Swagger开关配置API分组实体配置常用注解总结 简介: 前后端分离: 前端 ->前端控制层,视图 后端 ->后端控制层,服务层,数据访问层 前后端通过API进行交互 前后端相对独立且松耦合 产生的问题: 前后端集成,前端或者后端无法左到"“及时协商,今早解决”",最终问题集中爆发 Swag
SpringBoot集成Swagger
weixin_45974277的博客
02-17 1748
SpringBoot集成Swagger => springfox，两个jar包 Springfox-swagger2 swagger-swagger-ui 添加Maven依赖 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.spring
Swagger入门教程
03-03
Swagger能成为最受欢迎的RESTAPIs文档生成工具之一，有以下几个原因：Swagger可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。Swagger可以生成客户端SDK代码用于各种不同的平台上的实现。...
spring-boot-cxf-jaxrs:使用Spring Boot和CXF JAXRS快速入门
05-14
快速入门使用Spring Boot来配置一个小的应用程序，其中包括启用了Swagger的CXF JAXRS端点。 重要的 该快速入门可以在2种模式下运行：在您的计算机和Kubernetes / OpenShift群集上独立运行 部署选项 您可以在以下...
SpringBoot整合Mybatis集成Swagger简易教程
10-27
.description("这是一个使用SpringBoot、Mybatis和Swagger构建的简单API示例") .version("1.0") .build(); } } ``` 最后，启动SpringBoot应用，Swagger UI可以通过http://localhost:8080/swagger-ui.html 访问...
quickstart-jakarta-ee-guides：适用于多个应用程序服务器的Jakarta EE快速入门指南
02-04
【标题】：Jakarta EE快速入门指南 - 多应用服务器支持 【描述】：Jakarta EE（前身为Java EE）是企业级Java应用程序开发的框架，它提供了多种服务和组件，用于构建分布式、多层的Web应用。快速入门指南旨在帮助...
springboot及swagger2整合报错：documentationPluginsBootstrapper
hunkxia的专栏
10-19 4948
在使用高版本Springboot(2.7.4)与Swagger版本整合的时候，启动报错，最终找到解决方案
Swagger快速入门
11-06
Swagger的快速入门.文档中五部便可以将Swagger跑起来.
springboot系列学习（二十二）：swagger这个就是一个工具 ，这个是可以生成项目的开发文档，swagger界面的详解和配置类的详解（一）
一天不写代码难受的博客
10-04 1718
主要利用这个工具生成开发文档，让前端后端工程师使用这个文档开发代码，前后台耦合性变小。 现在前后端开发出现的问题 前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发 解决方法：Swagger 首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险 号称世界上最流行的API框架 Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新 直接运行，在线测试API 支持多种语言 （如：Java，PHP等） 官网：https://
swagger 介绍及两种使用方法
热门推荐
程序猿-HZQ
04-26 22万+
一：swagger是什么？ 1、是一款让你更好的书写API文档的规范且完整框架。 2、提供描述、生产、消费和可视化RESTful Web Service。 3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。 二：使用第三方依赖（最简单的方法） 1、在pom.xml文件中添加第三方swagger依赖（） &amp;lt;dependen...
Spring Boot中使用Swagger2构建强大的RESTful API文档
weixin_34072458的博客
04-18 6067
由于Spring Boot能够快速开发、便捷部署等特性，相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因，这些终端会共用很多底层业务逻辑，因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。 这样一来，我们的RESTful API就有...
前后端分离使用swagger生成接口文档快速使用方式
m0_37830775的博客
04-02 2602
swagger的使用 最近公司使用了前后端分离的的形式，第一次接触到了swagger这个工具，在与前端配合的过程中踩了很多坑，今天抽出时间来记录一下。本人小白说错了请使劲喷。 日（粘）常（贴）简（复）介（制）: Swagger 是一套围绕 OpenAPI 规范构建的开源工具，可以帮助您设计，构建，记录和使用 REST API。 Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化...
【Java】基础知识复习清单，你能口述这些概念吗
C+=UI~(Nip)
07-12 3123
目录结构 数据类型与运算符 计算 计算方法 运算 逻辑运算符 数据转换 表达式的自动转换 不同数据类型的强制转换 布尔值自动转换 自动转换类型 位运算符 Hello_Java 不同赋值方法 对于镜度数的第一次简介 进制数写法 数据类型 流程控制与数组 数组 深入了解数组 使用数组 数组类型 画圆–作业题目 foreach语句 面向对象 方法详解 参数传递 ...
swagger 超简单入门教程 使用（真实自测）
xmind果果
09-17 1万+
ps 网上swagger 的资料比较多，开发时还是遇到不少坑的，所以自己进行一下整理自己的学习过程 教程：（如果想快速入门，强烈建议，链接中的博客暂时只看我建议的部分） —————————–我是无敌的搬运工（如有需要，我会整合成一个系列文章）——————————— 1.安装，集成到springboot 方式一 纯注解式 http://blog.didispace.com/spr...
API管理工具Swagger介绍及Springfox原理分析
云栖社区
06-19 739
云栖君导读：swagger是一个API框架，号称世界上最流行的API工具。它提供了API管理的全套解决方案，比如API在线编辑器，API UI展示界面，代码生成器等诸多功...
swagger ui 怎么输入对象_小胖连 Swagger 的实现原理都不知道？真的菜！
weixin_42266267的博客
12-22 247
点击上方一个优秀的废人，选择设为星标优质文章，及时送达巨人的肩膀：http://r6d.cn/SVuZ开篇先说一说 Springfox 和 Swagger 的关系Swagger 是一种规范。springfox-swagger 是基于 Spring 生态系统的该规范的实现。springfox-swagger-ui 是对 swagger-ui 的封装，使得其可以使用 Spring 的服务...
swagger小白学习总结
最新发布
02-21
Swagger小白学习总结主要关注的是Swagger在现代软件开发中的应用，特别是与SpringBoot项目的集成。Swagger是一个强大的工具，用于生成RESTful API的自动文档，它简化了前后端开发者之间的通信和接口文档的维护。 1....

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

抵扣说明：

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

余额充值