Spring boot 多模块项目 + Swagger 让你的API可视化

释放双眼,带上耳机,听听看~!

Spring boot 多模块项目 + Swagger 让你的API可视化

前言

手写 Api 文档的几个痛点:

  • 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。
  • 接口返回结果不明确
  • 不能直接在线测试接口,通常需要使用工具,比如postman
  • 接口文档太多,不好管理

为了前后台更好的对接,为了以后交接方便,为了不再长篇大论的手写 api 文档,那么就来用Swagger吧(不是打广告,确实强),它可以轻松的整合到 Spring 中,它既可以减少我们手写 api 文档的时间,同时又将说明文档整合到我们的代码中,这样前台看着也方便,后台工作也舒坦。

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单(其他好处网上自己搜在这里就不再多说了)。

官网地址: https://swagger.io/

本篇内容:

(1)构建多模块项目(可选单模块步骤)
(2)pom.xml 配置加载依赖
(3)Swagger 配置类(Bean)
(4)启动类配置
(5)创建工具类
(6)User 实例类
(7)定义 restful 接口(Controller 层)

为帮助快速入门上手使用,提供了简单的增删改查,使用的参数配置示例

本篇测试环境:

  • SpringBoot 2.0.5.RELEASE
  • Swagger 2.9.2
  • JDK 1.8.191

成功截图:

第一步:构建多模块项目(可选步骤)

如果想使用多模块,请先构建项目(建议):

如果不想使用多模块(下面模块请根据自己项目修改)

所有涉及到的文件结构:

第二步:pom.xml 配置加载依赖

Spring boot 项目都会有一些依赖,为了更直观,只贴必要的部分
为你的 Spring Boot 项目再增加下面两个依赖:
pom.xml 配置:

<!--可以去下面地址查看最近版本-->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

第三步:Swagger 配置类(Bean)

注意:

  • basePackage 是需要自己配置的,换成自己需要扫描的包,会扫描其所有子包
  • 一个就配主模块,多个就配大包,或分开配

用 @Configuration 注解该类,等价于XML中配置beans;
用 @Bean 标注方法等价于XML中配置bean
不是不可以使用 xml,提倡使用注解,是不是想起点什么?

SwaggerConfig.java 源代码:

package com.xpwi.main.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * 描述:Swagger2 Config Bean
 *
 * @author Xiao Pengwei
 * @since 2019-03-27
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(\"com.xpwi\"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(\"SpringBoot使用Swagger构建api文档\")
                .description(\"简单优雅的 restfun 风格 https://icode.blog.csdn.net\")
                .termsOfServiceUrl(\"https://icode.blog.csdn.net\")
                .version(\"1.0\")
                .build();
    }
}

第四步:启动类配置

Application.class 加上注解 @EnableSwagger2 表示开启Swagger

package com.xpwi.main;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.Date;

/**
 * 描述:Spring Boot 多模块测试项目
 * @author Xiao Pengwei
 * @since  2019-03-25
 */

@EnableSwagger2
@SpringBootApplication
@RestController
//扫描 main,test 模块中的下的所有包
//在 pom 加载子模块依赖才可以扫包
@ComponentScan({\"com.xpwi.main\",\"com.xpwi.test\",\"com.xpwi.login\"})
public class App {

    public static void main(String[] args) {
        //启动 Web 容器
        SpringApplication.run(App.class, args);
        System.out.println(\"[启动成功]\"+new Date());
    }
}

第五步:创建工具类

用于返回通用数据格式的工具类
CommonResult.java 源代码:

package com.xpwi.main.util;

/**
 * 描述:通用返回类型
 * @author Xiao Pengwei
 * @since  2019-03-27
 */
public class CommonResult {

    private String status;

    private Object result;

    private Object message;

    public String getStatus() {
        return status;
    }

    public void setStatus(String status) {
        this.status = status;
    }

    public Object getResult() {
        return result;
    }

    public void setResult(Object result) {
        this.result = result;
    }

    public Object getMessage() {
        return message;
    }

    public void setMessage(Object message) {
        this.message = message;
    }
}

第六步:User 实例类

User 模拟对应数据库字段的实体类
User.java 源代码:

package com.xpwi.main.entity;

import java.util.Date;

/**
 * 描述:User 实体类
 * @author Xiao Pengwei
 * @since  2019-03-27
 */
public class User {
    private String id;
    private String username;
    private int age;
    private Date ctm;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public Date getCtm() {
        return ctm;
    }

    public void setCtm(Date ctm) {
        this.ctm = ctm;
    }
}

第七步:!定义 restful 接口(Controller 层)

最重要的一步,也是开发中最常用的一步
创建 UserController.java 源代码:

package com.xpwi.main.controller;

import com.xpwi.main.entity.User;
import com.xpwi.main.util.CommonResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
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 springfox.documentation.annotations.ApiIgnore;

import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * 描述:Controller 类
 * @author Xiao Pengwei
 * @since  2019-03-27
 */
@RestController
@Api(value = \"用户测试模块\")
public class UserController {

    // 创建线程安全的Map
    static Map<String, User> users = Collections.synchronizedMap(new HashMap<String, User>());

    /**
     * 根据ID查询用户
     * @param id
     * @return
     */
    @ApiOperation(value=\"获取用户详细信息\", notes=\"根据url的id来获取用户详细信息\")
    @ApiImplicitParam(name = \"id\", value = \"用户ID\", required = true, dataType = \"String\", paramType = \"path\")
    @RequestMapping(value = \"user/{id}\", method = RequestMethod.GET)
    public ResponseEntity<CommonResult> getUserById (@PathVariable(value = \"id\") String id){
        CommonResult commonResult = new CommonResult();
        try {
            User user = users.get(id);
            commonResult.setResult(user);
            commonResult.setStatus(\"ok\");
        } catch (Exception e) {
            commonResult.setResult(e.getClass().getName() + \":\" + e.getMessage());
            commonResult.setStatus(\"error\");
            e.printStackTrace();
        }
        return ResponseEntity.ok(commonResult);
    }

    /**
     * 查询用户列表
     * @return
     */
    @ApiOperation(value=\"获取用户列表\", notes=\"获取用户列表\")
    @RequestMapping(value = \"users\", method = RequestMethod.GET)
    public ResponseEntity<CommonResult> getUserList (){
        CommonResult commonResult = new CommonResult();
        try {
            List<User> userList = new ArrayList<User>(users.values());
            commonResult.setResult(userList);
            commonResult.setStatus(\"ok\");
        } catch (Exception e) {
            commonResult.setResult(e.getClass().getName() + \":\" + e.getMessage());
            commonResult.setStatus(\"error\");
            e.printStackTrace();
        }
        return ResponseEntity.ok(commonResult);
    }

    /**
     * 添加用户
     * @param user
     * @return
     */
    @ApiOperation(value=\"创建用户\", notes=\"根据User对象创建用户\")
    @ApiImplicitParam(name = \"user\", value = \"用户详细实体user\", required = true, dataType = \"User\")
    @RequestMapping(value = \"user\", method = RequestMethod.POST)
    public ResponseEntity<CommonResult> add (@RequestBody User user){
        CommonResult commonResult = new CommonResult();
        try {
            users.put(user.getId(), user);
            commonResult.setResult(user.getId());
            commonResult.setStatus(\"ok\");
        } catch (Exception e) {
            commonResult.setResult(e.getClass().getName() + \":\" + e.getMessage());
            commonResult.setStatus(\"error\");

            e.printStackTrace();
        }
        return ResponseEntity.ok(commonResult);
    }

    /**
     * 根据id删除用户
     * @param id
     * @return
     */
    @ApiOperation(value=\"删除用户\", notes=\"根据url的id来指定删除用户\")
    @ApiImplicitParam(name = \"id\", value = \"用户ID\", required = true, dataType = \"String\", paramType = \"path\")
    @RequestMapping(value = \"user/{id}\", method = RequestMethod.DELETE)
    public ResponseEntity<CommonResult> delete (@PathVariable(value = \"id\") String id){
        CommonResult commonResult = new CommonResult();
        try {
            users.remove(id);
            commonResult.setResult(id);
            commonResult.setStatus(\"ok\");
        } catch (Exception e) {
            commonResult.setResult(e.getClass().getName() + \":\" + e.getMessage());
            commonResult.setStatus(\"error\");

            e.printStackTrace();
        }
        return ResponseEntity.ok(commonResult);
    }

    /**
     * 根据id修改用户信息
     * @param user
     * @return
     */
    @ApiOperation(value=\"更新信息\", notes=\"根据url的id来指定更新用户信息\")
    @ApiImplicitParams({
            @ApiImplicitParam(name = \"id\", value = \"用户ID\", required = true, dataType = \"String\",paramType = \"path\"),
            @ApiImplicitParam(name = \"user\", value = \"用户实体user\", required = true, dataType = \"User\")
    })
    @RequestMapping(value = \"user/{id}\", method = RequestMethod.PUT)
    public ResponseEntity<CommonResult> update (@PathVariable(\"id\") String id, @RequestBody User user){
        CommonResult commonResult = new CommonResult();
        try {
            User user1 = users.get(id);
            user1.setUsername(user.getUsername());
            user1.setAge(user.getAge());
            users.put(id, user1);
            commonResult.setResult(user1);
            commonResult.setStatus(\"ok\");
        } catch (Exception e) {
            commonResult.setResult(e.getClass().getName() + \":\" + e.getMessage());
            commonResult.setStatus(\"error\");

            e.printStackTrace();
        }
        return ResponseEntity.ok(commonResult);
    }

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

第八步:启动 Spring Boot,打开浏览器

只需访问:

http://localhost:8080/swagger-ui.html

swagger-ui.html 是默认的,不用担心自己没有创建这个文件,这个就是那个 UI 咯

第九步:常用注解

swagger 提供的常用的注解有:

  • @Api:用在类上,说明该类的作用
  • @ApiOperation:用在方法上,说明方法的作用,标注在具体请求上,value 和 notes 的作用差不多,都是对请求进行说明;tags 则是对请求进行分类的,比如你有好几个 controller,分别属于不同的功能模块,那这里我们就可以使用 tags 来区分了。
  • @ApiImplicitParams:用在方法上包含一组参数说明
  • @ApiImplicitParam:用在 @ApiImplicitParams 注解中,指定一个请求参数的各个方面。
  • @ApiResponses:用于表示一组响应
  • @ApiResponse:用在 @ApiResponses 中,一般用于表达一个错误的响应信息
  • @ApiModel:描述一个 Model 的信息(这种一般用在post创建的时候,使用
    @RequestBody 这样的场景,请求参数无法使用 @ApiImplicitParam 注解进行描述的时候)表明这是一个被 swagger 框架管理的 model,用于class上
  • @ApiModelProperty: 这里顾名思义,描述一个 model 的属性,就是标注在被标注了 @ApiModel 的class的属性上,这里的 value 是对字段的描述,example 是取值例子,注意这里的 example很有用,对于前后端开发工程师理解文档起到了关键的作用,因为会在 api 文档页面上显示出这些取值来;这个注解还有一些字段取值,可以自己研究,举例说一个:position,表明字段在 model 中的顺序。

第十步:使用

一般 swagger 需要一下api的权限,需要在对应的模块进行排除:
http://localhost:8080/swagger-resources/configuration/ui
http://localhost:8080/swagger-resources
http://localhost:8080/api-docs
http://localhost:8080/swagger-ui.html
http://localhost:8080/swagger-resources/configuration/security

如果项目上线并且需要关闭 swagger 接口,可以通过配置权限,或者再 SwaggerConfig 里面
return new Docket 的时候加多一个.enable(false)

技术朋友群

人已赞赏
随笔日记

Docker运行oracle12c注意事项

2020-11-9 4:02:34

随笔日记

mint-ui Infinite scroll 重复加载、加载无效的原因及解决方案

2020-11-9 4:02:36

0 条回复 A文章作者 M管理员
    暂无讨论,说说你的看法吧
个人中心
购物车
优惠劵
今日签到
有新私信 私信列表
搜索