概述

首先让我引用 Swagger 官方的介绍:

Design is the foundation of your API development. Swagger makes API design a breeze, with easy-to-use tools for developers, architects, and product owners.

设计是API开发的基础。Swagger使API设计变得轻而易举,为开发人员,架构师和产品所有者提供了易于使用的工具。

作为一个后端开发者,你是否为开发完 API 接口后为写文档而烦恼、当 App 开发人员或前端开发人员看不懂的你写的接口文档,你还得去给他们讲一遍怎么使用而烦恼。

使用 Swagger 这些烦恼统统的消失,Swagger一个集预览和测试于一身的在线可视化 RESTful 风格的 Web 服务框架。

闲话少说,直接开整!

基础配置和 API 接口开发

第一步:先引入Swagger starter 依赖到 pom 文件中。我们这里采用2.7.0 版本

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

还有一点需要注意的是必须引入 Spring Boot Web starter 依赖。

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

第二步:编写 RESTful API 服务:一个用户的增删改查。

public class User {

        private String name;
        private Integer age;
        //......省略get and set方法
}

定义用户 RESTFull API 服务 Controller。

@RestController()
@RequestMapping("/user")
public class UserController {
//......
}

在 RESTFull API 服务 Controller 添加根据 id查询用户的接口


    /**
     * 根据用户id 查询用户
     * @return
     */
    @GetMapping("/{id}")
    public User get(@PathVariable(name = "id") Long id){
        User user = new User();
        user.setName("lijunkui");
        user.setAge(18);
        log.info("springboot查询用户成功:"+"id:{}",id);
        return user;
    }

定义添加用户接口。

/**
     * 添加用户
     */
    @PostMapping()
    public void add(User user){
        log.info("springboot添加用户成功:"+"name:{},age:{}",user.getName(),user.getAge());
    }

定义更新用户接口。

 /**
     * 全部更新
     * @param user
     */
    @PutMapping()
    public void updatePut(User user){
        log.info("springboot Put 修改用户成功:"+"name:{},age:{}",user.getName(),user.getAge());
     }

定义 局部更新用户接口。

 /**
     * 局部更新
     */
    public void updatePatch(@PathVariable("name") String name){
        log.info("springboot Patch 修改用户成功:"+"name:{}",name);
    }

定义删除用户接口。

  /**
     * 删除用户
     */
    @DeleteMapping("/{id}")
    public void delete(@PathVariable("id") Long id){
        User user = new User();
        user.setName("lijunkui");
        user.setAge(18);
        log.info("springboot 删除用户成功:"+"id:{}",id);
    }

定义根据 json 数据更新用户接口。

 /**
     * 根据requestBody 更新用户信息
     * @param user
     * @return
     */
    @PostMapping("/updateUserByRequestBody")
    public void updateUserByRequestBody(@RequestBody User user){
        log.info("updateUserByRequestBody 修改用户成功:"+"name:{},age:{}",user.getName(),user.getAge());
    }

第三步:编写 Swagger 的Config配置类


//让Spring来加载该类配置
@Configuration
//是否禁用swagger 的配置
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
//启用Swagger2
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket alipayApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("简单用户管理API接口文档")
                .apiInfo(apiInfo())
                .select()
 //扫描配置 classpath 路径配置 Swagger注解下的 Api文档。 .apis(RequestHandlerSelectors.basePackage("com.ljk.springBootLearn.users"))
                .paths(PathSelectors.any()).build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SprignBoot学习专栏")
                .description("集成swagger")
                .termsOfServiceUrl("https://blog.csdn.net/ljk126wy")
                //创建人
                .contact(new Contact("桌前明月", "http://www.baidu.com", ""))
                //版本
                .version("1.0")
                //API 描述
                .description("简单介绍如有问题还望指正")//
                .build();
    }
}

我来简单介绍一下 Swagger 的配置类中方法使用介绍。

每一组 Controller 的 Api 都对应一个 Docket 配置 ,如果有多个组 Api 就应该配置多个Docket 的 Bean。

Docket.groupName(String name):配置接口分组的名称,name为分组的名称。对应下图中红色框中的信息

apiInfo(ApiInfo apiInfo ) 配置Api 文档的一些公共的描述信息,对应下图中红色框中的信息。


paths():配置需要显示具体 Api 的路径。

我们通过PathSelectors类的4个方法来进行判断

  1. PathSelectors.any(): 所有的api都显示
  2. PathSelectors.none(): 所有的路径都不显示
  3. PathSelectors.regex(String pathRegex): 按照String的matches方法进行匹配。例如:PathSelectors.regex("/user/*")
  4. PathSelectors.ant(String antPattern): 按照Spring的AntPathMatcher提供的match方法进行匹配 例如:PathSelectors.ant("/user/**")

AntPathMatcher.match(String pattern, String path) 可以做URLs匹配,规则如下

?匹配一个字符

*匹配0个或多个字符

** 匹配0个或多个目录

第四步:在application.properties 或 application.yml中添加配置信息。
在application.properties 配置信息如下:

server.port=8080
server.servlet.context-path=/sbe
swagger.enable = true
application.yml 配置内容如下:

application.yml 配置信息如下:

server:
  port: 8080 #游览器访问项目端口号
  servlet:
    context-path:/sbe #游览器访问项目的名称
swagger:
  enable: true

需要注意的是application.properties 或 application.yml 只能存在一个,swagger.enable =
true表示是否使用Swagger的的功能。主要用于生产环境和开发环境的配置。切记生产环境要配置成false。

到目前为止SpringBoot 整合 Swagger 基础部分搭建完毕!接下来让我们今天的重点 Swagger 配置注解。

Swagger 注解使用实战

@Api : 说明接口类的作用。

@Api(tags ="用户管理")
@RestController()
@RequestMapping("/user")
public class UserController {
}

访问 Swagger UI 界面如下:


@ApiOperation: 用在方法上 说明方法的作用。

    @ApiOperation(value="根据id获取用户信息")
    @GetMapping("/{id}")
    public User get(@PathVariable(name = "id") Long id){
      //省略逻辑代码
    }

访问 Swagger UI 界面如下:

@ApiImplicitParam: 方法中参数的说明

 /**
     * 根据用户id 查询用户
     * @return
     */
    @ApiImplicitParam(paramType= "path", name = "id", value = "用户id", required = true, dataType = "Long")
    @GetMapping("/{id}")
    public User get(@PathVariable(name = "id") Long id){
       //省略逻辑代码
    }

访问 Swagger UI 界面如下:

@ApiImplicitParams(): 配置多个ApiImplicitParam


    @ApiImplicitParams({

@ApiImplicitParam(name="name",value="用户名",dataType="string", required = true, paramType = "form",example="ljk"),
@ApiImplicitParam(name="age",value="用户年龄",dataType="int", paramType = "form")})

    @PostMapping()

    public void add(User user){
      //省略逻辑代码
    }

访问 Swagger UI 界面如下:

@ApiModel: 描述返回实体类信息

@ApiModel(value="user对象",description="用户对象user")
public class User {
}

@ApiModelProperty: 描述返回实体类属性的信息

public class User {
    @ApiModelProperty(value="用户名",name="name",example="xingguo")
    private String name;
    @ApiModelProperty(value="年龄1",name="age",required=true)
    private Integer age;
}

访问 Swagger UI 界面如下:

@ApiResponse: 错误相应信息描述
@ApiResponses: 描述多个错误信息


    @GetMapping("/{id}")
    @ApiResponses({ @ApiResponse(code = 400, message = "请求无效 (Bad request)") })
    public User get(@PathVariable(name = "id") Long id){
     //省略逻辑代码
    }

访问 Swagger UI 界面如下:


@ApiParam: 用于声明通过request接受的参数。
@ApiIgnore(): 忽略的字段不显示在api文档中。

public void logon(
@ApiParam(name="loginName",value="登录名称",required=true)
@RequestParam String loginName,
@ApiParam(name="password",value="密码",required=true)
@RequestParam String password,
@ApiIgnore()Model model,HttpServletRequest request){
}

启动 SpringBoot 项目访问:localhost:8080/sbe/swagger-ui.html 如下图所示:

我们可以在如下图中的 name 和 age 输入框中输入内容并进行测试,这里就不一个个进行测试啦。

小结

SpringBoot 整合 Swagger 需要通过SpringBoot Java Config的方式配置 Api 接口扫描的路径、接口组介绍、接口版本、接口描述等信息。接下来就是 Swagger 的具体配置注解,常用的配置注解如下:

@Api :说明接口类的作用。

@ApiOperation:用在方法上 说明方法的作用。

@ApiImplicitParam:方法中参数的说明。

@ApiImplicitParams():配置多个 ApiImplicitParam

@ApiModel:描述返回实体类信息。

@ApiModelProperty:描述返回实体类属性的信息。

@ApiResponse:错误相应信息描述。

@ApiResponses:描述多个错误信息。

@ApiParam:用于声明通过request接受的参数。

@ApiIgnore():忽略的字段不显示在api文档中。

如果你还没有操作过,可以跟着博客敲一遍哈!

代码示例

文中的代码可以参考我的 GitHub 仓库名称 springbootexamples 中的 spring-boot-2.x-swagger 进行查看

GitHub:https://github.com/zhuoqianmingyue/springbootexamples

示例程序环境版本:

SpringBoot Version:2.1.0.RELEASE
SpringMVC Version:5.1.2RELEASE
Maven Version:3.2.5
JDK Version:1.8.0_144

玩转 SpringBoot 2 快速整合 | 丝袜哥(Swagger)的更多相关文章

  1. 玩转 SpringBoot 2 快速整合 | JSP 篇

    前言 JavaServer Pages(JSP)技术使Web开发人员和设计人员能够快速开发和轻松维护利用现有业务系统的信息丰富的动态Web页面. 作为Java技术系列的一部分,JSP技术可以快速开发独 ...

  2. 玩转 SpringBoot 2 快速整合拦截器

    概述 首先声明一下,这里所说的拦截器是 SpringMVC 的拦截器 HandlerInterceptor.使用SpringMVC 拦截器需要做如下操作: 创建拦截器类需要实现 HandlerInte ...

  3. 玩转 SpringBoot 2 快速整合 | FreeMarker篇

    FreeMarker 介绍 Apache FreeMarker™是一个模板引擎:一个Java库,用于根据模板和更改数据生成文本输出(HTML网页,电子邮件,配置文件,源代码等).模板是用FreeMar ...

  4. 玩转 SpringBoot 2 快速整合 | Thymeleaf 篇

    前言 Thymeleaf是一个适用于Web和独立环境的现代服务器端Java模板引擎. Thymeleaf的主要目标是为您的开发工作流程带来优雅的自然模板 - 可以在浏览器中正确显示的HTML,也可以用 ...

  5. 玩转 SpringBoot 2 快速整合 Filter

    概述 SpringBoot 中没有 web.xml, 我们无法按照原来的方式在 web.xml 中配置 Filter .但是我们可以通过 JavaConfig(@Configuration +@Bea ...

  6. 玩转 SpringBoot 2 之整合 JWT 下篇

    前言 在<玩转 SpringBoot 2 之整合 JWT 上篇> 中介绍了关于 JWT 相关概念和JWT 基本使用的操作方式.本文为 SpringBoot 整合 JWT 的下篇,通过解决 ...

  7. 使用Springboot + Gradle快速整合Mybatis-Plus

    使用Springboot + Gradle快速整合Mybatis-Plus 作者:Stanley 罗昊 [转载请注明出处和署名,谢谢!] MyBatis-Plus(简称 MP)是一个 MyBatis ...

  8. 玩转 SpringBoot 2 快速搭建 | RESTful Api 篇

    概述 RESTful 是一种架构风格,任何符合 RESTful 风格的架构,我们都可以称之为 RESTful 架构.我们常说的 RESTful Api 是符合 RESTful 原则和约束的 HTTP ...

  9. 玩转 SpringBoot 2 之整合 JWT 上篇

    前言 该文主要带你了解什么是 JWT,以及JWT 定义和先关概念的介绍,并通过简单Demo 带你了解如何使用 SpringBoot 2 整合 JWT. 介绍前在这里我们来探讨一下如何学习一门新的技术, ...

随机推荐

  1. IIS短文件名漏洞复现

    IIS短文件名漏洞复现 一.漏洞描述 此漏洞实际是由HTTP请求中旧DOS 8.3名称约定(SFN)的代字符(~)波浪号引起的.它允许远程攻击者在Web根目录下公开文件和文件夹名称(不应该可被访问). ...

  2. 【Kali】kali linux的安装

    资源准备 制作U盘启动盘 准备kali_Linux的分区 禁用快速启动 安装kali_linux 在这篇Blog中笔者将会讲解如何安装kali_linux,kali可以安装到虚拟机上,但这里笔者强烈建 ...

  3. PageHelper分页实战(SSM整合)

    步骤一:引入SSM相关的jar包,包列表如下: 步骤二:创建或修改配置文件,配置文件清单如下: applicationContext.xml <?xml version="1.0&qu ...

  4. Android UI绘制流程及原理

    一.绘制流程源码路径 1.Activity加载ViewRootImpl ActivityThread.handleResumeActivity() --> WindowManagerImpl.a ...

  5. Python之assert断言语句

    关键字assert构成断言语句,主要是可以在我们书写一个新的程序时,可以使用它帮我们锁定bug范围. 表达式: assert 表达式 ‘窗口提示的信息’ 括号中的项目为选填项目,选填项目将会在表达式的 ...

  6. Linux基础用户管理

    一.用户管理 (一).用户和组的基本概念 Users and groups:. Every process (running program) on the system runs as a part ...

  7. ImageView 使用详解

    极力推荐文章:欢迎收藏 Android 干货分享 阅读五分钟,每日十点,和您一起终身学习,这里是程序员Android 本篇文章主要介绍 Android 开发中的部分知识点,通过阅读本篇文章,您将收获以 ...

  8. npm包开发与发布

    把通用的功能开发成npm包,便用使用和维护,更重要的是可以分享给广大的开发者,是不是很激动人心! 那么,步骤如下: 1.创建项目 创建项目目录,npm init ,根据需要输入配置信息(建完后也可以在 ...

  9. 【数据结构学习】关于HashMap的那些事儿

    涉及数据结构 红黑树 链表 哈希 从CRUD说起 预热知识: DEFAULT_INITIAL_CAPACITY = 1 << 4, HashMap默认容量为16(n << m意 ...

  10. Java下载文件方法

    public static void download(String path, HttpServletResponse response) { try { // path是指欲下载的文件的路径. F ...