概述

首先让我引用 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. CHM格式

    转载请标明出处:https://www.cnblogs.com/tangZH/p/11176995.html CHM格式为CHM头,CHM头节,内容三部分组成. 总体格式图: 初始化头包含了CHM的相 ...

  2. jsp数据交互(一).1

    一.jsp中java小脚本1.<% java代码段%>2.<% =java表达式%>不能有分号3.<%!成员变量和函数声明%>二.注释1.<!--html注释 ...

  3. 搭建PowerDNS+LAP+NFS+MySQL主从半节点同步实现LAMP架构

    实验环境:(共7台机器) PowerDNS: 192.168.99.110    两台LAP: 192.168.99.120 和 192.168.99.130 NFS服务器:192.168.99.14 ...

  4. 【Android】未引入包问题

    Mac 上配置 Android 开发环境,遇到了下面问题: /Users/***/Documents/SVN/Android/***/1.0.3/res/values/styles.xml:21: e ...

  5. 用python绘制漂亮的图形

    先看效果,没有用任何绘图工具,只是运行了一段python代码. 代码如下: _ = ( 255, lambda V ,B,c :c and Y(V*V+B,B, c -1)if(abs(V)<6 ...

  6. 免安装版tomcat安装成服务

    安装方式(前提已经安装好了jdk,并配置了环境量): (1) 下载非exe的tomcat zip包: (2) 解压缩,如:D:\tomcat: (3) 进入D:\tomcat\bin,修改servic ...

  7. HelloDjango 系列教程:Django 的接客之道

    文中涉及的示例代码,已同步更新到 HelloGitHub-Team 仓库 Web 服务简单的说就是处理请求,每个请求就像是一个"顾客".首先热情地把顾客迎接进来,然后满足用户的个性 ...

  8. 【Java例题】2.5 温度转换

    5.输入华氏温度, 用下列公式将其转换为摄氏温度并输出. C=5/9(F-32). package study; import java.util.Scanner; public class demo ...

  9. 【POJ - 2236】Wireless Network (并查集)

    Wireless Network 这接翻译了 Descriptions 地震发生在东南亚.ACM(亚洲合作医疗团队)已经与膝上电脑建立了无线网络,但是一次意外的余震袭击,网络中的所有计算机都被打破了. ...

  10. react学习(一)--JSX简介

    由于在中国银联实习的项目要用到react,所以不得不硬着头皮把react学习一下.这是要往全栈发展吗0.0 正文: 一个最简单的React例子如下, ReactDOM.render( <h1&g ...