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的入门篇就说到这，还有一些其他的注解，以后再进行分享。例如: