Swagger上手教程

一、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接口文档

转载于:https://my.oschina.net/u/565068/blog/716760