SpringBoot入门篇3 -- 整合Swagger

写在前面

距离上一次分享整合SpringBoot过去了大半年了，时光荏苒，今天将继续更新SpringBoot的相关技术点。

Swagger

这里，我就不过多介绍Swagger是什么了，相信你看这文章的时候也是有了解Swagger的相关概念的。简单的说，Swagger就是一种定义接口信息的规范。具体可以参见Swagger官网（https://swagger.io）

SpringBoot整合Swagger

下面分享一下SpringBoot整合Swagger的内容，看一下如何在一个既有的SpringBoot工程下整合Swagger。

SpringBoot初始工程

启动类 SpringbootSwaggerApplication.java

package top.flygrk.ishare.springbootswagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringbootSwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringbootSwaggerApplication.class, args);
    }

}

实体类 User.java

注意：这里采用lombok插件及注解

package top.flygrk.ishare.springbootswagger.entity;

import lombok.Data;

/**
 * @Package top.flygrk.ishare.springbootswagger.entity
 * @Author wuzy
 * @Date 2019/8/5 11:05
 * @Version V1.0
 * @Description:
 */
@Data
public class User {
    private String id;
    private String username;
    private int age;
    private String note;
}

接口类 UserController.java

我们这里有2个api接口：插入用户insert和根据用户id查询用户信息。这里均采用模拟的方式，无service及dao层的处理逻辑。

package top.flygrk.ishare.springbootswagger.controller;

import com.alibaba.fastjson.JSONObject;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import top.flygrk.ishare.springbootswagger.entity.User;

/**
 * @Package top.flygrk.ishare.springbootswagger.controller
 * @Author wuzy
 * @Date 2019/8/5 11:07
 * @Version V1.0
 * @Description: 用户接口
 */
@RestController
@RequestMapping("user")
public class UserController {
    /**
    * @Authod wuzy
    * @Date 2019/8/5 11:09
    * @Method insert
    * @Param    user
    * @ReturnType Object
    * @Description: 插入用户信息
    */
    @RequestMapping(value = "insert", method = RequestMethod.POST)
    public Object insert(@RequestBody User user) {
        JSONObject jsonObject = new JSONObject();
        if (user == null) {
            jsonObject.put("result", "failed");
            jsonObject.put("reason", "user is null");
            return jsonObject;
        }
        jsonObject.put("result", "success");
        jsonObject.put("msg", user.getUsername());
        return jsonObject;
    }

    @RequestMapping(value = "findById", method = RequestMethod.GET)
    public Object findById(String id) {
        JSONObject jsonObject = new JSONObject();
        if (StringUtils.isEmpty(id)) {
            jsonObject.put("result", "failed");
            jsonObject.put("reason", "user is null");
            return jsonObject;
        }
        jsonObject.put("id", id);
        jsonObject.put("username", "wuzy");
        jsonObject.put("age", 20);
        jsonObject.put("note", "coding boy");
        return jsonObject;
    }

}

Swagger简单使用

我们先来看下如何初步使用Swagger，最方便的一种。首先添加maven依赖，然后再引入Swagger的注解即可。我们来仔细看看：

引入pom依赖

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

      <dependency>
          <groupId>com.spring4all</groupId>
          <artifactId>swagger-spring-boot-starter</artifactId>
          <version>1.9.0.RELEASE</version>
      </dependency>

添加Swagger注解

我们只需要在启动类SpringbootSwaggerApplication添加注解@EnableSwagger2Doc，即可完成对Swagger的简单整合，是不是so easy!!!

@SpringBootApplication
@EnableSwagger2Doc
public class SpringbootSwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootSwaggerApplication.class, args);
    }

}

验证

我们启动程序，去验证一下是否可以使用Swagger。我们通过访问http://127.0.0.1:9000/swagger-ui.html，可以看到如下界面：

我们再展开看下user-controller下的内容：


从上图可以看出，再user-controller下，存在两个接口，分别为/user/findById 和 /user/insert。同时也可以看出其访问方式为GET/POST信息。我们以 /user/findById为例，来看下其具体内容：



我们可以看到其需要的请求参数为id，类型为String等信息。并且我们可以使用后面的【Try it out】按钮，调用findById接口。我们来调用一下试试：

Swagger补充

有没有觉得上面简单的那个Swagger-UI很难阅读？那么下面，我们继续来优化下他的提示信息，我们通过相关注解来具体的描述接口的相关信息，比如类的含义、接口的含义、参数的含义等信息，具体代码如下：

UserController.java

package top.flygrk.ishare.springbootswagger.controller;

import com.alibaba.fastjson.JSONObject;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import top.flygrk.ishare.springbootswagger.entity.User;

/**
 * @Package top.flygrk.ishare.springbootswagger.controller
 * @Author wuzy
 * @Date 2019/8/5 11:07
 * @Version V1.0
 * @Description: 用户接口
 */
@RestController
@RequestMapping("user")
@Api("用户管理模块")
public class UserController {
    /**
    * @Authod wuzy
    * @Date 2019/8/5 11:09
    * @Method insert
    * @Param    user
    * @ReturnType Object
    * @Description: 插入用户信息
    */
    @RequestMapping(value = "insert", method = RequestMethod.POST)
    @ApiOperation(value = "插入用户信息", notes = "插入用户的详细信息")
    public Object insert(@RequestBody User user) {
        JSONObject jsonObject = new JSONObject();
        if (user == null) {
            jsonObject.put("result", "failed");
            jsonObject.put("reason", "user is null");
            return jsonObject;
        }
        jsonObject.put("result", "success");
        jsonObject.put("msg", user.getUsername());
        return jsonObject;
    }

    @RequestMapping(value = "findById", method = RequestMethod.GET)
    @ApiOperation(value = "查询用户信息", notes = "根据id查询用户信息")
    public Object findById(@ApiParam(value = "用户id", required = true) String id) {
        JSONObject jsonObject = new JSONObject();
        if (StringUtils.isEmpty(id)) {
            jsonObject.put("result", "failed");
            jsonObject.put("reason", "user is null");
            return jsonObject;
        }
        jsonObject.put("id", id);
        jsonObject.put("username", "wuzy");
        jsonObject.put("age", 20);
        jsonObject.put("note", "coding boy");
        return jsonObject;
    }

}

User.java

package top.flygrk.ishare.springbootswagger.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @Package top.flygrk.ishare.springbootswagger.entity
 * @Author wuzy
 * @Date 2019/8/5 11:05
 * @Version V1.0
 * @Description:
 */
@Data
@ApiModel
public class User {
    @ApiModelProperty(value = "用户id", required = true, dataType = "String")
    private String id;
    @ApiModelProperty(value = "用户名", dataType = "String")
    private String username;
    @ApiModelProperty(value = "年纪", dataType = "int")
    private int age;
    @ApiModelProperty(value = "备注", dataType = "String")
    private String note;
}

进行上述修改之后，我们再次启动SpringBoot工程，打开Swagger-UI，可以看到内容如下：


首先，展开看一下“查询用户信息接口”，可以看出在id后面的Description下有“用户id”的提示信息：


然后，我们来仔细看看insert接口的信息:


关于注解的说明本文暂时不再叙述，请大家参阅其他资料。整合Swagger的入门篇就说到这，还有一些其他的注解，以后再进行分享。例如:


最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 216,372评论 6赞 498
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 92,368评论 3赞 392
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 162,415评论 0赞 353
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 58,157评论 1赞 292
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 67,171评论 6赞 388
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 51,125评论 1赞 297
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 40,028评论 3赞 417
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 38,887评论 0赞 274
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 45,310评论 1赞 310
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 37,533评论 2赞 332
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 39,690评论 1赞 348
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 35,411评论 5赞 343
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 41,004评论 3赞 325
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 31,659评论 0赞 22
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 32,812评论 1赞 268
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 47,693评论 2赞 368
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 44,577评论 2赞 353