转载

SpringBoot如何优雅地使用Swagger2

前言

Spring Boot 框架是目前非常流行的微服务框架，我们很多情况下使用它来提供 Rest API。而对于 Rest API 来说很重要的一部分内容就是文档，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，这一点对于保证 API 文档的及时性将有很大的帮助。本文将使用 Swagger 2 规范的 Springfox 实现来了解如何在 Spring Boot 项目中使用 Swagger，主要包含了如何使用 Swagger 自动生成文档、使用 Swagger 文档以及 Swagger 相关的一些高级配置和注解。

Swagger 简介

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。Swagger 主要包含了以下三个部分：

Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。

Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。

Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

为什么要使用 Swagger

当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式，下面我们就来了解一下它的优点：

代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。

跨语言性，支持 40 多种语言。

Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。

还可以将文档规范导入相关的工具（例如 SoapUI）, 这些工具将会为我们自动地创建自动化测试。

以上这些优点足以说明我们为什么要使用 Swagger 了，您是否已经对 Swagger 产生了浓厚的兴趣了呢？下面我们就将一步一步地在 Spring Boot 项目中集成和使用 Swagger，让我们从准备一个 Spring Boot 的 Web 项目开始吧。

SpringBoot整合Swagger2

1.首先创建一个基础的SpringBoot web项目。您可以通过 Spring Initializr 页面生成一个空的 Spring Boot 项目，或者通过idea创建一个SpringBoot项目

2.添加依赖

Spring Boot 的 Web 依赖

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
</dependency>

集成swagger2

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

集成Swagger UI

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

3.java中Swagger2配置-直接上配置代码，Swagger2的配置是比较容易的，在成功项目创建之后，只需要开发者自己提供一个Docket的Bean。（注释写的很清楚，这里就不一一解释了。不懂的地方可以在片尾关注我公众号加我WX。）

/**
 * 集成swagger2 解决前后端分离 弊端：不能及时协商+今早解决的问题
 *   使用swagger总结:
 *     通过swagger 给一些比基奥难理解的接口或属性，增加注释信息
 *     接口文档实时更新
 *     可以在线测试
 *   安全问题:
 *     正式上线的时候 记得关闭swagger
 */
@Configuration//加载到springboot配置里面
@EnableSwagger2//开启swagger2
public class SwaggerConfig {
  /**
   * 配置swagger2
   * 注册一个bean属性
   * swagger2其实就是重新写一个构造器，因为他没有get set方法/
   * enable() 是否启用swagger false swagger不能再浏览器中访问
   * groupName()配置api文档的分组 那就注册多个Docket实例 相当于多个分组
   * @return
   */
  @Bean
  public Docket docket() {

    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .groupName("XXX")//组名称
        .enable(true)
        .select()
        /**
         * RequestHandlerSelectors配置扫描接口的方式
         *   basePackage 配置要扫描的包
         *   any 扫描全部
         *   none 不扫描
         *   withClassAnnotation 扫描类上的注解
         *   withMethodAnnotation 扫描方法上的注解
         */
        .apis(RequestHandlerSelectors.basePackage("com.tinygray.madison.controller"))
        /**
         * paths() 扫描过滤方式
         *   any过滤全部
         *   none不过滤
         *   regex正则过滤
         *   ant过滤指定路径
         */
//        .paths(PathSelectors.ant("/login/**"))
        .build();
  }

  /**
   * 配置swagger2信息 =apiInfo
   * @return
   */
  public ApiInfo apiInfo(){
    /*作者信息*/
//    Contact contact = new Contact("XXX", "http://baidu.com", "email");
    Contact contact = new Contact("", "", "");
    return new ApiInfo(
        "XXX的API接口",
        "company接口",
        "V1.0",
        "urn:toVs",
        contact,
        "Apache 2.0",
        "http://www.apache.org/licenses/LICENSE-2.0",
        new ArrayList());
  }

}

4.编写一些简单的java接口。（你可以根据你的情况进行编写）

@Api(tags = "TestController测试")
@RestController
public class TestController {
  @ApiOperation("login api")
  @GetMapping("/")
  public String login() {
    return "Hello login ~";
  }

  @ApiOperation("helloWord Api")
  @GetMapping("/index")
  public String index() {
    return "Hello World ~";
  }

  @ApiOperation("admin Api")
  @GetMapping("/admin/hello")
  public String admin() {
    return "hello admin!";
  }

  @ApiOperation("user Api")
  @GetMapping("/user/hello")
  public String user() {
    return "hello user";
  }
}

5.验证代码-到这里我们已经成功集成Swagger2，然后启动项目，输入 http://localhost:8080/swagger-ui.html ，如果能出现下面界面，说明配置成功了。

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持我们。

时间：2020-07-07

SpringBoot集成Swagger2实现Restful(类型转换错误解决办法)

pom.xml增加依赖包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <

Spring Boot整合Swagger2的完整步骤详解

前言 swagger,中文"拽"的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅, 而且还提供了在线文档的测试.另外swagger很容易构建restful风格的api. 一.Swagger概述 Swagger是一组围绕OpenAPI规范构建的开源工具,可帮助设计.构建.记录和使用REST API. 简单说下,它的出现就是为了方便进行测试后台的restful形式的接口,实现动态的更新,当我们在后台的接口修改了后,swagger可以实现自动的更新,而不需要

spring boot 2整合swagger-ui过程解析

这篇文章主要介绍了spring boot 2整合swagger-ui过程解析,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下 1.添加mvn依赖修改pom.xml加入 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.5.0</v

spring boot整合Swagger2的示例代码

Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步.Swagger 让部署管理和使用功能强大的API从未如此简单. 1.代码示例 1).在pom.xml文件中引入Swagger2 <dependency> <groupId>io.springfox</groupId> <artifa

Spring boot集成swagger2生成接口文档的全过程

一.Swagger介绍 Swagger是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的web服务.目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器.这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口开发文档,并且支持做测试的一款中间软件. 二.使用swagger优势 1.对于后端开发人员来说不用再手写Wiki接口拼大量参数,避免手写错误对代码侵入性低,采用全注解的方式,开发简单方法参数名修改.

springboot中swagger快速启动流程

介绍可能大家都有用过swagger,可以通过ui页面显示接口信息,快速和前端进行联调. 没有接触的小伙伴可以参考官网文章进行了解下demo页面. 多应用当然在单个应用大家可以配置SwaggerConfig类加载下buildDocket,就可以快速构建好swagger了. 代码大致如下: /** * Swagger2配置类 * 在与spring boot集成时,放在与Application.java同级的目录下. * 通过@Configuration注解,让Spring来加载该类配置. * 再

SpringBoot＋Swagger-ui自动生成API文档

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染.先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远. 这样后段开发好了api 之后就要提交api 文档给前端的朋友.给前端的api 文档各个公司有各个公司的要求,有的是word 有的是 md 文档,或者是 postman 的一个连接. 好了废话不多说说一下 swagger -ui 吧什么是Swagger Swagger是一个Restful风格接口的文档在线自动生成和测试的框架官网:http://swag

SpringBoot整合Swagger2实例方法

在进行软件开发的时候免不了要写接口文档,这些文档需要明确写出接口的类型.请求的URL.传参和返回值格式等信息,用于和前端交互或者提供给测试进行接口测试.但是手写文档一方面带给我们很大的工作量,另一方面如果接口有变更则需要频繁修改并且发给相关的人,无形中增加了工作量.小编为大家介绍一个生成文档的工具Swagger,上手简单,学习成本低,非常适合开发SpringBoot项目,现在就跟着小编一起学习吧. 首先需要在pom文件中加入swagger2的依赖,依赖的jar包如下图所示. <dependenc

SpringBoot整合Swagger2代码实例

首先遵循SpringBoot的三板斧第一步添加依赖  <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>{version}</version> <

SpringBoot整合Swagger和Actuator的使用教程详解

前言本篇文章主要介绍的是SpringBoot整合Swagger(API文档生成框架)和SpringBoot整合Actuator(项目监控)使用教程. SpringBoot整合Swagger 说明:如果想直接获取工程那么可以直接跳到底部,通过链接下载工程代码. Swagger 介绍 Swagger 是一套基于 OpenAPI 规范构建的开源工具,可以帮助我们设计.构建.记录以及使用 Rest API.Swagger 主要包含了以下三个部分: Swagger Editor:基于浏览器的编辑器,我们

SpringBoot整合MyBatis逆向工程及 MyBatis通用Mapper实例详解

一.添加所需依赖,当前完整的pom文件如下: <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd&q

spring-boot整合dubbo:Spring-boot-dubbo-starter

为什么要写这个小工具如果你用过Spring-boot来提供dubbo服务,相信使用中有很多"不爽"的地方.既然使用spring boot,那么能用注解的地方绝不用xml配置,这才是spring-boot-style.开个玩笑,真正意思是,spring-boot适合一些简单的.独立的服务,一个大的系统是不适合使用spring-boot来开发.相反,spring-boot适合那些简单服务的搭建. 网上大多数的方法还是使用xml配置,通过@Import注解来引入xml配置. 怎么使用对于

springboot整合redis进行数据操作(推荐)

redis是一种常见的nosql,日常开发中,我们使用它的频率比较高,因为它的多种数据接口,很多场景中我们都可以用到,并且redis对分布式这块做的非常好. springboot整合redis比较简单,并且使用redistemplate可以让我们更加方便的对数据进行操作. 1.添加依赖 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starte

springboot整合spring-data-redis遇到的坑

描述使用springboot整合redis,使用默认的序列化配置,然后使用redis-client去查询时查询不到相应的key. 使用工具发现,key的前面多了/xAC/xED/x00/x05t/x00!这样一个串. 而且value也是不能直观可见的. 问题所在使用springdataredis,默认情况下是使用org.springframework.data.redis.serializer.JdkSerializationRedisSerializer这个类来做序列化. org.spri

SpringBoot整合Shiro的代码详解

shiro是一个权限框架,具体的使用可以查看其官网 http://shiro.apache.org/ 它提供了很方便的权限认证和登录的功能. 而springboot作为一个开源框架,必然提供了和shiro整合的功能!接下来就用springboot结合springmvc,mybatis,整合shiro完成对于用户登录的判定和权限的验证. 1.准备数据库表结构这里主要涉及到五张表:用户表,角色表(用户所拥有的角色),权限表(角色所涉及到的权限),用户-角色表(用户和角色是多对多的),角色-权限表

原文 https://www.zhangshengrong.com/p/ERNnqdQBa5/

正文到此结束