开源的API文档工具框架——Swagger简介
初次接触Swagger是在2017年5月,当时公司正好要对整套系统架构进行重新设计,有同事推荐用这个技术框架来规范后台接口的API文档。当时因为架构重构,涉及改造的技术点太多,一时也就没太多精力,把Swagger暂时放下了。对于API文档我们就自己定义了一个模板,统一要求开发人员把文档写在tower上了。
现在回头来看,存在这么几个问题:
1. 文档编写及修改的及时性不够,由于API在开发及测试过程中经常会有调整,相应的文档不能及时得到修改。
2. 文档的规范性需要人为的检查来约束,增大了项目管理的工作量
3. 前端和测试人员对文档的理解有一个过程,有时需要频繁和后台开发人员进行交流,产生了一定的交流成本。
由于现在的互联网项目都是前后端合作的形式,前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,在这样的情况下,我又把注意力再次投向了Swagger。经过几天研究,大致有了比较清晰的认识,准备写几篇博客对这个技术进行一下说明。
Swagger这个单词做形容词是 “炫耀的;时髦的” 这样一个意思。官网地址:https://swagger.io,官网对其项目的定义是:
Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.
中文意思是:Swagger是一个大型的API开发者的工具框架,该框架提出了一个编写OpenAPI的规范(命名为OAS),并且Swagger可以跨整个API生命周期进行开发,从设计和文档到测试和部署。
Swagger这个框架的原理:框架提出了一个文档规范OAS,且提供了相应的可视化编辑器可以编辑这个文档以及对文档格式进行校验,文档的存储格式可是XML或者JSON形式的文件(后面简称API元文件),围绕着API元文件框架提供了对API元文件进行可视化展示的工具,展示的时候可以自定义模板,展示的方式是浏览器的网页形式(也就是一个 可交互的web系统),并且支持对AIP接口的在线的交互测试。同时社区还开发了一些集成框架,以便让Swagger能和例如SpringMVC这样的框架很好的整合,通过在Controller上写注解就可以自动生成相应的API文档。更有意思的是Swagger还提供了根据API元文件生成客户端调用代码和服务端Stub代码的功能。
Swagger框架从宏观上来看,我个人觉得可以分为三部分:
- 提供了一个编写API文档的规范 ,称为OAS ,在规范中明确API的格式和一些编写要素
- 提供相关的工具,对API文档的编写提供辅助。主要是这么几个项目 Swagger Editor、Swagger UI、Swagger Codegen、Swagger Inspector。
- 提供对各种流行语言和框架的集成,例如集成SpringMVC 的 springfox 框架
开源的API文档工具框架——Swagger简介的更多相关文章
- API文档工具-Swagger的集成
最近安装了API文档工具swagger,因为Github上已有详细安装教程,且安装过程中没有碰到大的阻碍,所以此文仅对这次安装做一份大致记录 相关网站 Swagger 官方地址: http://swa ...
- Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2
1. 引言 各位在开发的过程中肯定遇到过被接口文档折磨的经历,由于 RESTful 接口的轻量化以及低耦合性,我们在修改接口后文档更新不及时,导致接口的调用方(无论是前端还是后端)经常抱怨接口与文档不 ...
- 开源API文档工具- swagger2 与 smart-doc 比较 与 使用
工具开源地址 swagger2 : https://swagger.io/ smart-doc: https://www.oschina.net/p/smart-doc 国产 两者的比较 swagg ...
- 开源的api文档管理系统
api文档 php 在项目中,需要协同开发,所以会写许多API文档给其他同事,以前都是写一个简单的TXT文本或Word文档,口口相传,这种方式比较老土了,所以,需要有个api管理系统专门来管理这些ap ...
- 再见丑陋的 SwaggerUI,这款开源的API文档生成神器界面更炫酷,逼格更高!
一般在使用 Spring Boot 开发前后端分离项目的时候,都会用到 Swagger.Swagger 是一个规范和完整的框架,用于生成.描述.调试和可视化 RESTful 风格的 Web API 服 ...
- ASP.NET CORE 1.0 MVC API 文档用 SWASHBUCKLE SWAGGER实现
from:https://damienbod.com/2015/12/13/asp-net-5-mvc-6-api-documentation-using-swagger/ 代码生成工具: https ...
- 20个GitHub最热门的Java开源项目:文档、框架、工具
专注于Java领域优质技术,欢迎关注 文章来源:JavaGuide 以下涉及到的数据统计,数据来源:https://github.com/trending/java?since=monthly[1] ...
- Net Core的API文档工具Swagger
一.安装swagger 新建一个net core的api项目,通过NuGet安装Swashbuckle.AspNetCore. 二.注册swagger服务 在Startup.cs中注册Swagger生 ...
- api文档工具
平台选型 Apidoc 文档参考:http://apidocjs.com 优点 文档齐全,操作简单,ui清晰,代码注解查询性强,语言支持多元化, ...
随机推荐
- Inception介绍(MySQL自动化运维工具)
Inception介绍 GitHub:https://github.com/mysql-inception/inception 文档:https://mysql-inception.github.io ...
- Vue less使用scope时渗入修改子组件样式
@deep: ~'>>>'; .wrap { @{deep} .component1 { width: 120px; } }
- 用Keras搞一个阅读理解机器人
catalogue . 训练集 . 数据预处理 . 神经网络模型设计(对话集 <-> 问题集) . 神经网络模型设计(问题集 <-> 回答集) . RNN神经网络 . 训练 . ...
- Spring Boot笔记五: Web开发之Webjar和静态资源映射规则
目录 Webjar /** 访问当前项目的任何资源 欢迎页 标签页图标 Webjar 开始讲到Spring Boot的Web开发了,先介绍Webjar,这个其实就是把一些前端资源以jar包的形式导入到 ...
- I/O模型之四:Java 浅析I/O模型(BIO、NIO、AIO、Reactor、Proactor)
目录: <I/O模型之一:Unix的五种I/O模型> <I/O模型之二:Linux IO模式及 select.poll.epoll详解> <I/O模型之三:两种高性能 I ...
- EL表达式获取日期时间类型后格式化的问题
最近在项目中遇到的问题,就是从后台取到的java.util.Date类型的数据,在前台需要格式化的问题. 开始想了很多办法,其实在JSP页面中处理很简单,JSTL提供的format标签即可解决这个问题 ...
- ajax、fetch、axios — 请求数据
jquery ajax jq 的ajax是对原生XHR的封装,除此以外还增添了对JSONP的支持.用起来非常方便 用法: $.ajax({ url:发送请求的地址, data:数据的拼接,//发送到服 ...
- [Android] Android 的singleLine废弃解决
之前写代码时,都没有注意singleLine已经废弃,每次想让TextView或Edittext单行显示都是直接使用,但是这样其实不好,因为废弃的函数可能在有的手机上出现问题,所以需要自己去找到替换的 ...
- 开发更健壮python程序的一些工具
在众多语言中, Java 生态系统发展得最好, 比如异常logging报警, 比如性能监控工具. Python其实生态也不错, 这里列出一些出色的工具. LogBook, 并结合 raven-pyth ...
- [译]Nuget.Server
原文 NuGet.Server是一个包,可用于使一个ASP.NET应用host一个package feed . 使用VS创建一个新的空WEB应用,添加Nuget.Server包. 配置应用的Packa ...