文档章节

Swagger上手教程

芝麻谷
 芝麻谷
发布于 2016/07/23 21:08
字数 1573
阅读 1.2K
收藏 0

一、Swagger是什么鬼?

What is Swagger?

The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.

Technically speaking - Swagger is a formal specification surrounded by a large ecosystem of tools, which includes everything from front-end user interfaces, low-level code libraries and commercial API management solutions.

   Swagger的目的是定义一种标准、语言无关针对REST API的接口,这种接口可以让人和计算机不通过查看源代码,文档或网络通信监控等方式,来了解服务的功能。通过Swagger的合理定义,客户可以非常容易的理解服务内容,轻松的和远程服务进行交互。与底层编程语言接口类似,Swagger消除了调用服务时对服务的猜测。

   技术上来说,Swagger是一个正式的标准,其庞大的生态系统提供了一系列工具,涵盖了从前端用户界面到底层代码库和商业API管理解决方案等。

二、Swagger怎么用?

How do I get started?

If you're an API provider and want to use Swagger to describe your APIs - there are several approaches available:

A top-down approach where you would use the Swagger Editor to create your Swagger definition and then use the integrated Swagger Codegen tools to generate server implementation. A bottom-up approach where you have an existing REST API for which you want to create a Swagger definition. Either you create the definition manually (using the same Swagger Editor mentioned above), or if you are using one of the supported frameworks (JAX-RS, node.js, etc), you can get the Swagger definition generated automatically for you. If you're doing JAX-RS have a look at the example at https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X. If on the other hand you're an API Consumer who wants to integrate with an API that has a Swagger definition you can use the online version of the Swagger UI to explore the API (given that you have a URL to the APIs Swagger definition) - and then use Swagger Codegen to generate the client library of your choice.

In either case - be sure to check out the long list of both open source projects and commercial vendors that are available for Swagger - perhaps there is something there targeting your specific needs.

对于API提供者,想通过Swagger来描述提供给客户的API,有以下几种方式可供选择:

自顶向下方式,使用Swagger Editor来创建Swagger定义,然后使用集成的Swagger Codegen(代码生成器)去生成服务端实现。 自底向上方式,如果你想用来创建Swagger Definition的REST API已经存在,你可以手动创建(Swagger Editor)Swagger定义。如果你用的是Swagger支持的框架(JAX-RS,NodeJS等),Swagger Definition可以自动生成。这里有一个应用JAX-RS的例子,点我。 对于API消费者,在需要集成Swagger定义的API时,可以在线上的Swagger UI中去浏览API(通过指向Swagger Definition的URL)然后按照你的选择来生成(Swagger Codegen)客户端依赖库。

不管哪种情况,在使用swagger时,请参考open souce project和commercial vendors这两个列表,也许有一些东西可以满足你的特别需求。

好了,在宏观上对Swagger有了一定的了解,现在开始来看下swagger相关的工具的用法。

Swagger-editor

1、Swagger-editor部署

官方提供了两种swagger-editor的使用方式,点我

Running Locally

Download the latest release (v2.10.3) and serve the static files via your HTTP server. If you don't have an HTTP server, you can use http-server Node.js module.

Using http-server module: npm install -g http-server wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.3/swagger-editor.zip unzip swagger-editor.zip http-server swagger-editor Building From Source

Make sure you have Node.js installed.

git clone https://github.com/swagger-api/swagger-editor.git cd swagger-editor npm install npm start 第一种方式有几处需要注意。首先,必须保证nodejs在本机已经安装,NodeJs安装教程。其次,运行http-server swagger-editor时,当前目录一定是swagger-editor的父目录,我在此处滞留了好久,启动服务后在浏览器打开后都是空白页。所以提醒大家一定要注意。

第二种方式我没有成功,在执行npm install时候,莫名其妙的假死且没有任何输出,估计是网络原因,但配饰了国内的NPM源以后仍然不能够解决,配置国内源的方法:点我。

在命令行中有如下显示则证明安装成功

[localhost:Documents houjinxin$ http-server swagger-editor

Starting up http-server, serving swagger-editor

Available on:

http://127.0.0.1:8080

http://10.88.188.112:8080

Hit CTRL-C to stop the server

2、如何用Swagger-editor编辑接口文档

   根据官方文档,Swagger-editor(以下简称SE)本身支持JSON和YAML两种格式的编辑,因为YAML格式对人类更加友好所以默认使用YAML这种格式,当然要转换成JSON只需要通过File -> download JSON即可。然后把json文件的内容拷贝到SE中,你会发现完全没问题。接下就要仔细看看SE提供demo以及swagger规范了,逐行对照规范中的说明即可。这里涉及到整套API中有哪些接口,接口有哪些方法,方法如何发送,响应是什么,都需要我们自己去定义。

3、接口设计完以后如何开发

   细心的你会发现,在使用SE设计接口时,右侧有一个预览视图,在预览中每个接口的下方都有一个试一试按钮。顾名思义,如果按照设计已经在服务端实现了这套接口,我们通过设置接口参数,其实直接就可以调用这套接口了。但是究竟如何做呢?

Swagger-UI

1、swagger-ui部署

1、下载swagger-ui的源代码

git clone https://github.com/swagger-api/swagger-ui.git

2、拷贝swagger-ui中的dist到其他目录,例如:~/Document,并且将dist改名为swagger-ui

3、进入~/Document,运行http-server swagger-ui。见到如下提示表示部署成功。

localhost:Documents houjinxin$ http-server swagger-ui

Starting up http-server, serving swagger-ui

Available on:

http://127.0.0.1:8080

http://10.88.188.112:8080

Hit CTRL-C to stop the server

其实任何容器都可以运行,只不过这里为了方便用了node的http-server组件。

然后在浏览器输入 http://127.0.0.1:8080 打开swagger-ui,既可看到默认的接口描述。

参考资料

作者访谈 通过Swagger进行API设计

官方文档 swagger官网

swagger规范

快速开始

swagger-editor 官方在线demo

swagger-ui

SpringFox文档

开发者博客 代码自动化生成

Swagger与SpringMVC集成

Swagger+Spring mvc生成Restful接口文档

© 著作权归作者所有

芝麻谷
粉丝 5
博文 3
码字总数 4761
作品 0
朝阳
程序员
私信 提问
加载中

评论(0)

Swagger环境搭建之非依赖代码法

前言 Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集...

易达
2016/10/15
1.2K
0
Spring Boot 学习资料收集

导读: 从第一次接触Spring Boot 至今已经有半年多了,在这期间也浏览了许多和Spring Boot 相关的书籍及文章,公司里面的许多项目也一直在使用Spring Boot。 关于Spring Boot的一些看法: Sp...

yangrd
2017/03/02
0
0
老雷/spring-boot-starter-swagger

spring-boot-starter-swagger 该项目是spring-boot与的整合,swagger是一款高效易用的嵌入式文档插件。引入该项目,可以让你的api发布更容易,修改发布更快捷,团队交流更高效。 本项目特点 ...

老雷
2017/09/18
0
0
基于Mock Server的前后端分离

基于API的前后台分离开发,帮助我们解决了前后台分工与通信的问题。 但是仍然有一些问题: 1.前台开发受限于后台开发的速度 2.后台提供给前台的接口缺字段,时常需要联调 3.Swagger API书写起...

欧钟源
2015/11/27
1.5K
0
SpringBoot整合Swagger测试api构建

什么是Swagger? Swagger是什么:THE WORLD’S MOST POPULAR API TOOLING 根据官网的介绍: Swagger Inspector:测试API和生成OpenAPI的开发工具。Swagger Inspector的建立是为了解决开发者的...

编程SHA
2019/02/17
44
1

没有更多内容

加载失败,请刷新页面

加载更多

docker上启动nginx,并配置修改nginx的配置文件

1.使用docker 下载nginx 镜像 docker pull nginx 2.启动nginx docker run --name nginx -p 80:80 -d nginx 这样就简单的把nginx启动了,但是我们想要改变配置文件nginx.conf ,进入容器,命令...

yuxw
4分钟前
27
0
管道符|重定向与环境变量

重定向 管道符 通配符 转义符 环境变量 重定向 重定向(把命令和文件结合起来使用) 输入重定向< 将文件重定向到命令里,让文件去匹配命令执行,与正常的名命令对文件的执行方向相反,但结果一...

Venus7
6分钟前
22
0
恢复丢失的Joomla密码的最常用方法

忘记密码是很常见的事情。有些用户将密码保存在其默认浏览器内存中,几个月后您可能会忘记任何事情。我们中有些人甚至不记得他们在Joomla安装时发出的密码。本文介绍了如何重置Joomla管理员密...

六艺网络专注于Joomla
9分钟前
42
0
更改后如何重新加载.emacs?

如何才能使Emacs重新加载在.emacs更新的所有定义,而无需重新启动Emacs? #1楼 在您的初始化文件中定义它,并通过Mx reload-user-init-file调用 (defun reload-user-init-file() (interact...

javail
15分钟前
32
0
我眼中的分布式系统可观测性

作者:黄东旭,PingCAP 联合创始人兼 CTO 位于 M87 中心的特大质量黑洞示意图(© EHT Collaboration) 今天的文章我想从这张模糊的照片说起。 相信很多小伙伴对这张照片并不陌生,这是去年人...

TiDB
16分钟前
57
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部