前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >一起来学SpringBoot | 第十一篇:集成Swagger在线调试

一起来学SpringBoot | 第十一篇:集成Swagger在线调试

作者头像
battcn
发布2018-08-03 12:14:15
4750
发布2018-08-03 12:14:15
举报
文章被收录于专栏:battcn

SpringBoot 是为了简化 Spring 应用的创建、运行、调试、部署等一系列问题而诞生的产物, 自动装配的特性让我们可以更好的关注业务本身而不是外部的XML配置,我们只需遵循规范,引入相关的依赖就可以轻易的搭建出一个WEB工程

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、前后端分离的形态,而且前端和后端在各自的技术道路上越走越远。

前端和后端的唯一联系,变成了API接口;API文档成了前后端开发人员联系的纽带,变得越来越重要, swagger就是一款让你更好的书写API文档的框架。

文档工具

没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,有在 Word上写的,有在对应的项目目录下 readme.md上写的,每个公司都有每个公司的玩法,无所谓好坏。

现如今市场上书写API文档的工具有很多,常见的有 postman、yapi、阿里的RAP 但是能称之为框架的,估计也只有 swagger了。

swagger 优缺点

  • 集成方便,功能强大
  • 在线调试与文档生成
  • 代码耦合,需要注解支持,但不影响程序性能

导入依赖

pom.xml 中添加 swagger-spring-boot-starter 的依赖

代码语言:javascript
复制
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.4.5-RELEASE</version>
</dependency>

属性配置

配置 spring.swagger.enabled开启 swagger的使用,如果在生产环境中不想用可以在对应的 profile下面将它设置为 spring.swagger.enabled=false,这样一来接口就不存在暴露的风险

代码语言:javascript
复制
# 扫描的包路径,默认扫描所有
spring.swagger.base-package=com.battcn
# 默认为 true
spring.swagger.enabled=true

实体类

swagger 提供了非常齐全的注解,为 POJO提供了 @ApiModel@ApiModelProperty,以便更好的渲染最终结果

代码语言:javascript
复制
package com.battcn.entity;

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

import java.io.Serializable;

/**
 * @author Levin
 * @since 2018/5/10 0007
 */
@ApiModel
public class User implements Serializable {

    private static final long serialVersionUID = 8655851615465363473L;

    private Long id;
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    // TODO  省略get set
}

restful 风格接口

注解描述

  • @Api 描述 Controller
  • @ApiIgnore 忽略该 Controller,指不对当前类做扫描
  • @ApiOperation 描述 Controller类中的 method接口
  • @ApiParam 单个参数描述,与 @ApiImplicitParam不同的是,他是写在参数左侧的。如( @ApiParam(name="username",value="用户名")Stringusername
  • @ApiModel 描述 POJO对象
  • @ApiProperty 描述 POJO对象中的属性值
  • @ApiImplicitParam 描述单个入参信息
  • @ApiImplicitParams 描述多个入参信息
  • @ApiResponse 描述单个出参信息
  • @ApiResponses 描述多个出参信息
  • @ApiError 接口错误所返回的信息
代码语言:javascript
复制
package com.battcn.controller;

import com.battcn.entity.User;
import com.battcn.swagger.properties.ApiDataType;
import com.battcn.swagger.properties.ApiParamType;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;

/**
 * swagger
 *
 * @author Levin
 * @since 2018/5/16 0016
 */
@RestController
@RequestMapping("/users")
@Api(tags = "1.1", description = "用户管理", value = "用户管理")
public class UserController {

    private static final Logger log = LoggerFactory.getLogger(UserController.class);

    @GetMapping
    @ApiOperation(value = "条件查询(DONE)")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
            @ApiImplicitParam(name = "password", value = "密码", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
    })
    public User query(String username, String password) {
        log.info("多个参数用  @ApiImplicitParams");
        return new User(1L, username, password);
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "主键查询(DONE)")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户编号", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH),
    })
    public User get(@PathVariable Long id) {
        log.info("单个参数用  @ApiImplicitParam");
        return new User(id, "u1", "p1");
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户(DONE)")
    @ApiImplicitParam(name = "id", value = "用户编号", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH)
    public void delete(@PathVariable Long id) {
        log.info("单个参数用 ApiImplicitParam");
    }

    @PostMapping
    @ApiOperation(value = "添加用户(DONE)")
    public User post(@RequestBody User user) {
        log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam");
        return user;
    }

    @PutMapping("/{id}")
    @ApiOperation(value = "修改用户(DONE)")
    public void put(@PathVariable Long id, @RequestBody User user) {
        log.info("如果你不想写 @ApiImplicitParam 那么 swagger 也会使用默认的参数名作为描述信息 ");
    }
}

测试

由于上面的接口是 restful 风格的接口,添加和修改无法通过浏览器完成,以前都是自己编写 junit或者使用 postman之类的工具。现在只需要打开浏览器输入 http://localhost:8080/swagger-ui.html,更多操作请自行体验...

总结

目前很多大佬都写过关于 SpringBoot 的教程了,如有雷同,请多多包涵,本教程基于最新的 spring-boot-starter-parent:2.0.2.RELEASE编写,包括新版本的特性都会一起介绍...

说点什么

全文代码:https://github.com/battcn/spring-boot2-learning/tree/master/chapter10

本文参与 腾讯云自媒体同步曝光计划,分享自微信公众号。
原始发表:2018-05-16,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 battcn 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 文档工具
  • 导入依赖
  • 属性配置
    • 实体类
      • restful 风格接口
        • 测试
        • 总结
        • 说点什么
        领券
        问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档