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

前言

swagger,中文“拽”的意思。它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,
而且还提供了在线文档的测试。另外swagger很容易构建restful风格的api。

一、Swagger概述

Swagger是一组围绕OpenAPI规范构建的开源工具,可帮助设计、构建、记录和使用REST API。

简单说下,它的出现就是为了方便进行测试后台的restful形式的接口,实现动态的更新,当我们在后台的接口

修改了后,swagger可以实现自动的更新,而不需要认为的维护这个接口进行测试。

二、Swagger常用注解

swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。

  • @Api:修饰整个类,描述Controller的作用
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiParam:单个参数描述
  • @ApiModel:用对象来接收参数
  • @ApiProperty:用对象接收参数时,描述对象的一个字段
  • @ApiResponse:HTTP响应其中1个描述
  • @ApiResponses:HTTP响应整体描述
  • @ApiIgnore:使用该注解忽略这个API
  • @ApiError :发生错误返回的信息
  • @ApiParamImplicitL:一个请求参数
  • @ApiParamsImplicit 多个请求参数

三、SpringBoot整合Swagger

3.1 添加依赖

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

3.2 添加SwaggerConfiguration

通过@Configuration注解,表明它是一个配置类,@EnableSwagger2开启swagger2。

apiINfo()配置一些基本的信息。apis()指定扫描的包会生成文档。

再通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会
展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来
展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容
(除了被@ApiIgnore指定的请求)。

package com.lance.learn.springbootswagger.configuration;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author lance(ZYH)
 * @function Swagger启动配置类
 * @date 2018-07-09 21:24
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

 /**
  * swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
  * @return
  */
 @Bean
 public Docket createRestfulApi(){
  return new Docket(DocumentationType.SWAGGER_2)
    .pathMapping("/")
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.lance.learn.springbootswagger.controller")) //暴露接口地址的包路径
    .paths(PathSelectors.any())
    .build();
 }

 /**
  * 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
  * @return
  */
 private ApiInfo apiInfo(){
  return new ApiInfoBuilder()
    //页面标题
    .title("Spring Boot 测试使用 Swagger2 构建RESTful API")
    //创建人
    .contact(new Contact("LanveToBigData", "http://www.cnblogs.com/zhangyinhua/", "917484312@qq.com"))
    //版本号
    .version("1.0")
    //描述
    .description("API 描述")
    .build();
 }
}

3.3 Controller文档内容

描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。

如下所示,我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam
注解来给参数增加说明。

1)实例一

package com.lance.learn.springbootswagger.controller;

import com.lance.learn.springbootswagger.bean.Book;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

import java.util.*;

/**
 * @author lance(ZYH)
 * @function
 * @date 2018-07-09 21:39
 */
@RestController
@RequestMapping(value = "/bookcurd")
public class BookController {
 Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());

 @ApiOperation(value="获取图书列表", notes="获取图书列表")
 @RequestMapping(value={""}, method= RequestMethod.GET)
 public List<Book> getBook() {
  List<Book> book = new ArrayList<>(books.values());
  return book;
 }

 @ApiOperation(value="创建图书", notes="创建图书")
 @ApiImplicitParam(name = "book", value = "图书详细实体", required = true, dataType = "Book")
 @RequestMapping(value="", method=RequestMethod.POST)
 public String postBook(@RequestBody Book book) {
  books.put(book.getId(), book);
  return "success";
 }
 @ApiOperation(value="获图书细信息", notes="根据url的id来获取详细信息")
 @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long",paramType = "path")
 @RequestMapping(value="/{id}", method=RequestMethod.GET)
 public Book getBook(@PathVariable Long id) {
  return books.get(id);
 }

 @ApiOperation(value="更新信息", notes="根据url的id来指定更新图书信息")
 @ApiImplicitParams({
   @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long",paramType = "path"),
   @ApiImplicitParam(name = "book", value = "图书实体book", required = true, dataType = "Book")
 })
 @RequestMapping(value="/{id}", method= RequestMethod.PUT)
 public String putUser(@PathVariable Long id, @RequestBody Book book) {
  Book book1 = books.get(id);
  book1.setName(book.getName());
  book1.setPrice(book.getPrice());
  books.put(id, book1);
  return "success";
 }
 @ApiOperation(value="删除图书", notes="根据url的id来指定删除图书")
 @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long",paramType = "path")
 @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
 public String deleteUser(@PathVariable Long id) {
  books.remove(id);
  return "success";
 }

 @ApiIgnore//使用该注解忽略这个API
 @RequestMapping(value = "/hi", method = RequestMethod.GET)
 public String jsonTest() {
  return " hi you!";
 }
}

2)实例二

package com.lance.learn.springbootswagger.controller;

import com.lance.learn.springbootswagger.bean.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.*;

/**
 * @author lance(ZYH)
 * @function
 * @date 2018-07-09 22:00
 */

@RestController
@RequestMapping(value="/users")
public class UserDetailController {
  static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

  @ApiOperation(value="获取用户列表", notes="")
  @RequestMapping(value={""}, method= RequestMethod.GET)
  public List<User> getUserList() {
    List<User> r = new ArrayList<User>(users.values());
    return r;
  }

  @ApiOperation(value="创建用户", notes="根据User对象创建用户")
  @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
  @RequestMapping(value="", method=RequestMethod.POST)
  public String postUser(@RequestBody User user) {
    users.put(user.getId(), user);
    return "success";
  }

  @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
  @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
  @RequestMapping(value="/{id}", method=RequestMethod.GET)
  public User getUser(@PathVariable Long id) {
    return users.get(id);
  }

  @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象,并根据传过来的user信息来更新用户详细信息")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
      @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
  })
  @RequestMapping(value="/{id}", method=RequestMethod.PUT)
  public String putUser(@PathVariable Long id, @RequestBody User user) {
    User u = new User();
    users.put(id, u);
    return "success";
  }

  @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
  @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
  @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
  public String deleteUser(@PathVariable Long id) {
    users.remove(id);
    return "success";
  }
}

3.4 web界面查看

四、项目代码地址

https://github.com/LanceToBigData/SpringBootLearning/tree/develop/SpringBoot-Swagger

总结

以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,如果有疑问大家可以留言交流,谢谢大家对我们的支持。

(0)

相关推荐

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

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

  • 详谈springboot过滤器和拦截器的实现及区别

    前言 springmvc中有两种很普遍的AOP实现: 1.过滤器(Filter) 2.拦截器(Interceptor) 本篇面对的是一些刚接触springboot的人群 所以主要讲解filter和interceptor的简单实现和它们之间到底有什么区别 (一些复杂的功能我会之后发出文章,请记得关注) Filter的简单实现 字面意思:过滤器就是过滤的作用,在web开发中过滤一些我们指定的url 那么它能帮我们过滤什么呢? 那功能可就多了: 比如过拦截掉我们不需要的接口请求 修改请求(reques

  • 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引入拦截器并放行swagger代码实例

    这篇文章主要介绍了Springboot引入拦截器并放行swagger代码实例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下 Springboot引入拦截器 自定义的拦截器类 Interceptor package cn.zytao.taosir.auth.config; import javax.annotation.Resource; import javax.servlet.http.HttpServletRequest; import j

  • 详解SpringBoot结合swagger2快速生成简单的接口文档

    1. pom.xml中加入依赖 <dependency> <groupId>com.spring4all</groupId> <artifactId>swagger-spring-boot-starter</artifactId> <version>1.8.0.RELEASE</version> </dependency> 2. 在启动类(即带@SpringBootApplication这个注解的类)上添加@E

  • spring-boot 禁用swagger的方法

    在使用spring-boot开发的时候,我们很多时候会使用swagger作为api文档输出.可以在UI界面上看到api的路径,参数等等. 当然,作为开发环境是很方便的,但是上生产环境的时候,我们需要把swagger禁掉.怎么通过配置文件的方法来禁用swagger呢? 代码如下: import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.cont

  • SpringBoot结合Swagger2自动生成api文档的方法

    首先在pom.xml中添加如下依赖,其它web,lombok等依赖自行添加 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.spri

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

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

  • Spring Boot整合Redis的完整步骤

    前言 实际 开发 中 缓存 处理是必须的,不可能我们每次客户端去请求一次 服务器 ,服务器每次都要去 数据库 中进行查找,为什么要使用缓存?说到底是为了提高系统的运行速度.将用户频繁访问的内容存放在离用户最近,访问速度最 快的 地方,提高用户的响 应速度,今天先来讲下在 springboot 中整合 redis 的详细步骤. 一.Spring Boot对Redis的支持 Spring对Redis的支持是使用Spring Data Redis来实现的,一般使用Jedis或者lettuce(默认),

  • Spring Boot应用Docker化的步骤详解

    概述 Spring Boot简化了Spring应用的开发过程,遵循约定优先配置的原则提供了各类开箱即用(out-of-the-box)的框架配置.另一方面,Spring Boot还具备将代码直接构建为可执行jar包的能力,这个jar包是一个可以独立运行的部署单元.基于以上特性,现在普遍认为Spring Boot提供了一种快速构造微服务(Micro-Service)的能力. 当下web服务端开发中最火的名词中绝对有微服务的一席之地,其也成为当下互联网后端服务架构演进历程中最闪亮的技术之一.微服务的

  • 通过Spring Boot整合Mybatis分析自动配置详解

    前言 SpringBoot凭借"约定大于配置"的理念,已经成为最流行的web开发框架,所以有必须对其进行深入的了解:本文通过整合Mybatis类来分析SpringBoot提供的自动配置(AutoConfigure)功能,在此之前首先看一个整合Mybatis的实例. SpringBoot整合Mybatis 提供SpringBoot整合Mybatis的实例,通过Mybatis实现简单的增删改查功能: 1.表数据 CREATE TABLE `role` ( `note` varchar(25

  • Spring Boot整合Web项目常用功能详解

    前言 在Web应用开发过程中,一般都涵盖一些常用功能的实现,如数据库访问.异常处理.消息队列.缓存服务.OSS服务,以及接口日志配置,接口文档生成等.如果每个项目都来一套,则既费力又难以维护.可以通过Spring Boot的Starter来将这些常用功能进行整合与集中维护,以达到开箱即用的目的. 项目基于Spring Boot 2.1.5.RELEASE 版. 项目地址 整个项目分为如下几部分: spring-boot-autoconfigure: 具体的各功能实现,每个功能通过package的

  • Spring Boot整合web层实现过程详解

    Spring Boot中对Spring MVC的文件上传是一脉相传的,我们双击shift去搜CommonsMultipartResolver这个类,它是文件上传的一个实现类.我们先看一下源码: 我们可以看到它是MultipartResolver的实现类,我们再Ctrl+H,就可以看到右侧MultipartResolver的两个实现类.第一个实现类在servlet3.0之后,什么都不用加,就可以直接使用.第二个实现类的兼容性要好一些,早期的servlet也可以使用,但需要自己额外的加依赖.那么在S

  • Spring Boot启动banner定制的步骤详解

    前言 爱美之心人皆有之,在 unix 和 linux 命令行环境下工作的闷骚程序员们可能也觉得命令行太单调了,而是他们就发明了在命令行下采用 ansii 字符输出各种图形的方式.这就是命令行下的 banner了,类似下面这样的 还有一些更闷骚的程序员甚至搞出了动态的 banner.例如在 linux(CentOS) 下执行下面的命令安装软件 sl sudo yum install sl 完成后,在命令行输入一个 sl -a 命令,就会看到一个小火车喷着浓烟,从右至左开过屏幕,上面还有两个小人在欢

  • spring boot整合Swagger2的示例代码

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

  • Springboot集成Spring Security实现JWT认证的步骤详解

    1 简介 Spring Security作为成熟且强大的安全框架,得到许多大厂的青睐.而作为前后端分离的SSO方案,JWT也在许多项目中应用.本文将介绍如何通过Spring Security实现JWT认证. 用户与服务器交互大概如下: 客户端获取JWT,一般通过POST方法把用户名/密码传给server: 服务端接收到客户端的请求后,会检验用户名/密码是否正确,如果正确则生成JWT并返回:不正确则返回错误: 客户端拿到JWT后,在有效期内都可以通过JWT来访问资源了,一般把JWT放在请求头:一次

  • Spring Boot thymeleaf模板引擎的使用详解

    在早期开发的时候,我们完成的都是静态页面也就是html页面,随着时间轴的发展,慢慢的引入了jsp页面,当在后端服务查询到数据之后可以转发到jsp页面,可以轻松的使用jsp页面来实现数据的显示及交互,jsp有非常强大的功能,但是,在使用springboot的时候,整个项目是以jar包的方式运行而不是war包,而且还嵌入了tomcat容器,因此,在默认情况下是不支持jsp页面的.如果直接以纯静态页面的方式会给我们的开发带来很大的麻烦,springboot推荐使用模板引擎. 模板引擎有很多种,jsp,

随机推荐