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,如果能出现下面界面,说明配置成功了。

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

(0)

相关推荐

  • SpringBoot整合Swagger2实例方法

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

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

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

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

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

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

  • SpringBoot+Swagger-ui自动生成API文档

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

  • springboot中swagger快速启动流程

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

  • 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

  • SpringBoot如何优雅地使用Swagger2

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

  • SpringBoot如何优雅的整合Swagger Api自动生成文档

    目录 前言 整合swagger api 自定义配置信息 简单使用 Swagger常用注解 Api标记 ApiOperation标记 ApiParam标记 ApiModel标记 ApiModelProperty标记 ApiIgnore标记 ApiImplicitParam标记 ApiImplicitParams标记 总结 前言 一个好的可持续交付的项目,项目说明,和接口文档是必不可少的,swagger api 就可以帮我们很容易自动生成api 文档,不需要单独额外的去写,无侵入式,方便快捷大大减少

  • Springboot如何优雅地进行字段校验

    差不多大半年没写文章了,终于将手头上的事忙完了,可以对外输出了.前段时间提交代码审核,同事提了一个代码规范缺陷:参数校验应该放在controller层.到底应该如何做参数校验呢 Controller层 VS Service层 去网上查阅了一些资料,一般推荐与业务无关的放在Controller层中进行校验,而与业务有关的放在Service层中进行校验.那么如何将参数校验写的优雅美观呢,如果都是if - else,就感觉代码写的很low,还好有轮子可以使用 常用校验工具类 使用Hibernate V

  • SpringBoot项目优雅的全局异常处理方式(全网最新)

    前言 在日常项目开发中,异常是常见的,但是如何更高效的处理好异常信息,让我们能快速定位到BUG,是很重要的,不仅能够提高我们的开发效率,还能让你代码看上去更舒服,SpringBoot的项目已经对有一定的异常处理了,但是对于我们开发者而言可能就不太合适了,因此我们需要对这些异常进行统一的捕获并处理. 一.全局异常处理方式一 SpringBoot中,@ControllerAdvice 即可开启全局异常处理,使用该注解表示开启了全局异常的捕获,我们只需在自定义一个方法使用@ExceptionHandl

  • 如何使用SpringBoot进行优雅的数据验证

    JSR-303 规范 在程序进行数据处理之前,对数据进行准确性校验是我们必须要考虑的事情.尽早发现数据错误,不仅可以防止错误向核心业务逻辑蔓延,而且这种错误非常明显,容易发现解决. JSR303 规范(Bean Validation 规范)为 JavaBean 验证定义了相应的元数据模型和 API.在应用程序中,通过使用 Bean Validation 或是你自己定义的 constraint,例如 @NotNull, @Max, @ZipCode , 就可以确保数据模型(JavaBean)的正确

  • Springboot项目优雅地处理日志的方法详解

    如上图,每天会生成一个新的日志文件,然后日志进行分类,我这里只对error和info进行分类. 怎么做呢? 首先,在resource目录创建一个新文件,取名logback-spring.xml <?xml version="1.0" encoding="UTF-8" ?> <configuration > <appender name="consoleLog" class="ch.qos.logback.c

  • SpringBoot 如何优雅的实现跨服务器上传文件的示例

    项目完整代码链接:代码链接 跨服务上传文件示意图 一.创建项目 springboot:2.2.6 JDK:1.8 由于资源有限,就用不同端口表示不同服务器了. 1.1 上传文件的项目 首先idea快速搭建工具创建一个springboot项目,名字为fileupload,作为上传文件的服务端. 选择spring web模块即可 配置相关参数 spring.servlet.multipart.enabled=true spring.servlet.multipart.max-file-size=30

  • 详解在SpringBoot如何优雅的使用多线程

    目录 快速使用 获取异步方法返回值 注意事项 本文带你快速了解@Async注解的用法,包括异步方法无返回值.有返回值,最后总结了@Async注解失效的几个坑. 在 SpringBoot 应用中,经常会遇到在一个接口中,同时做事情1,事情2,事情3,如果同步执行的话,则本次接口时间取决于事情1 2 3执行时间之和:如果三件事同时执行,则本次接口时间取决于事情1 2 3执行时间最长的那个,合理使用多线程,可以大大缩短接口时间.那么在 SpringBoot 应用中如何优雅的使用多线程呢? Don't

  • SpringBoot如何优雅的处理全局异常

    前言 本篇文章主要介绍的是SpringBoot项目进行全局异常的处理. SpringBoot全局异常准备 说明:如果想直接获取工程那么可以直接跳到底部,通过链接下载工程代码. 开发准备 环境要求 JDK:1.8 SpringBoot:1.5.17.RELEASE 首先还是Maven的相关依赖: <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <java.

  • SpringBoot如何优雅地处理全局异常详解

    前言 之前用springboot的时候,只知道捕获异常使用try{}catch,一个接口一个try{}catch,这也是大多数开发人员异常处理的常用方式,虽然屡试不爽,但会造成一个问题,就是一个Controller下面,满屏幕的try{}catch,看着一点都不优雅,一点都不符合小明的气质,憋了这么久,小明今天终于决定对所有异常实施统一处理的方案. 开发准备 JDK8.正常的springboot项目 代码编写 通用异常处理 其实Spring系列的项目全局异常处理方式早已存在,只不过我们一直忙于搬

随机推荐