专栏首页Java技术栈推荐一款接口 API 设计神器!

推荐一款接口 API 设计神器!

今天栈长给大家推荐一款接口 API 设计神器,传说中的,牛逼哄洪的 Swagger,它到底是什么?今天为大家揭开谜底!

Swagger是什么?

官网:https://swagger.io/

Swagger 如官网所示,它是最好的 API 构建工具。

它是一个围绕 OpenAPI 规范构建的开源工具,它可以帮助我们设计、构建、记录和使用 REST API 接口。

Swagger 包含的主要套件:

  • Swagger Editor - 基于浏览器的编辑器,用来编写 OpenAPI 规范。
  • Swagger UI - 基于 OpenAPI 规范动态生成 API 规范文档。
  • Swagger Codegen - 个模板驱动引擎,用来生成客户端代码。

图片来源见博客水印。

OpenAPI是什么?

上面有说到 Swagger 是一个围绕 OpenAPI 规范构建的开源工具,那么 OpenAPI 是什么呢?

OpenAPI 规范,以前叫 Swagger 规范。它是一个为 REST APIs的接口定义的规范。OpenAPI 可以定义的 API 实体内容包括以下几个部分。

  • 请求地址(如:/user)
  • 请求类型(如:GET、POST 等)
  • 请求参数
  • 响应参数
  • 验证方式
  • 文档信息:如联系人、许可证、服务条件等

这个 OpenAPI 规范可以用 YAML 或者 JSON 来编写,这种格式非常易于学习,可读性对开发人员非常友好。

完整的 OpenAPI 规范可以去官网看一下。

https://github.com/OAI/OpenAPI-Specification

编写文档地址:

http://editor.swagger.io/

为什么需要Swagger?

现在的互联网架构都是前后端分离的模式,还有现在是移动互联网时代了,APP 需要与后端服务器通信也需要维护一套接口,API文档自然就成了前后端开发人员联系的纽带。

编写 API 文档的方式也各有不同,有用 WORD 编写的,有用 confluence 等编写的,但这些方式都不能动态更新,每次接口变更都需要手动维护文档,甚是麻烦。

有了 Swagger,可以先做完接口,通过 Swagger 来动态生成和更新 API 文档。

本文分享自微信公众号 - Java技术栈(javastack),作者:栈长

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2019-02-20

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • Java 必须掌握的 12 种 Spring 常用注解!

    @Configuration 声明当前类为配置类,相当于xml形式的Spring配置(类上)

    Java技术栈
  • Java中的注解到底是如何工作的?

    自Java5.0版本引入注解之后,它就成为了Java平台中非常重要的一部分。开发过程中,我们也时常在应用代码中会看到诸如@Override,@Deprecate...

    Java技术栈
  • JAVA元注解@interface详解(@Target,@Documented,@Retention,@Inherited)。

    jdk1.5起开始提供了4个元注解,用来定义自定义注解的注解,它们分别是: @Target 指定注解使用的目标范围(类、方法、字段等),其参考值见类的定义:ja...

    Java技术栈
  • 快速学习-Swagger-UI

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

    cwl_java
  • Swift3.0带来的变化汇总系列二——集合类型中的变化

        与字符串类似,Swift中集合的类型在3.0版本中也做了大量API上面的修改。

    珲少
  • 【nodejs原理&源码赏析(6)】深度剖析cluster模块源码与node.js多进程(下)

    前两篇博文中已经分别介绍了使用cluster模块建立集群时主进程执行cluster.fork( )方法时的执行逻辑,以及net模块在不同场景下建立通讯的基本原理...

    大史不说话
  • Gatsby入门指南—使用GraphQL解析Markdown(2)

    这里是所有数据,传到了TitleAndDescription组件里,react组件数据传递,我这么就为了看着舒服一点。

    前端大彬哥
  • 趋势:从云到多云,超融合与云管平台(CMP)如期而遇

    在IT基础设施领域,超融合基础架构(Hyper-Converged Infrastructure,HCI,以下简称为超融合)在近几年备受瞩目,凭借井喷式的市场增...

    FIT2CLOUD飞致云
  • 最火爆的ROS教程-机器人操作系统入门-Melodic-

    原文链接:https://github.com/anchuanxu/ROS-Academy-for-Beginners...

    zhangrelay
  • 位运算权限控制

    大家玩Linux的时候应该知道读1写2执行4,其实这样的数据都是因为位运算 比如:在网站中经常使用的权限控制(增删改的权限)[很多大公司都是使用这个] 使用三位...

    苦咖啡

扫码关注云+社区

领取腾讯云代金券