swagger环境的搭建(swagger-editor|swagger-ui)

2016年12月10日 17:18:20

swagger环境的搭建(swagger-editor|swagger-ui)

在一些接口项目开发中,API文档一直是开发人员头疼的事情,如果没有一个好的接口文档,前后端的接口开发工作无法进行,这一点我深有体会。

作为一名java开发人员,在最近的项目中我也遇到了接口联调工作带来的烦恼,所以也尽快的希望能找到合适的API接口编写工具,在网上看到很多朋友说swagger是一款不错的Api编写工具,所以我抽了些时间对该工具进行了学习,以下是我在搭建环境时的一些体会,希望能帮助到同学们。


一、swagger-editor环境搭建

提示(重要):安装swagger前先去nodejs官网下载进行nodejs的安装,打开cmd命令测试安装结果,现在版本安装nodejs后node和npm会一并安装。安装后测试,如下图(若无法访问国外网站,本文所用到的安装文件在文章结尾处会统一上传):


1.打开swagger-editor官网,如果无法访问直接使用如下链接进行下载:GitHub:Swagger-editor,若github也无法访问详见最后文件下载地址。

2.下载后解压后运行如下命令  npm install -g http-server,这是指安装http-server服务器,-g是指全局安装,在安装nodejs时可指定全局位置,具体可以去网上搜索看如何指定位置,不指定也没影响,这里不详细说明

3.然后运行如下命令,启动该项目http-server swagger-editor,默认为8080端口 ,若想更换端口则使用如下命令 http-server –p 2008 swagger-editor,启动成功如下:

4.使用浏览器访问结果

5.swagger-editor主要是编写api接口文档,但需要配合swagger-ui来查看,里面的代码格式为yaml,不用慌,可能你需要学着看官方文档进行编写,熟练就好了,耽误不了多少时间(工欲善其事必先利其器),努力吧。


二、swagger-ui官方版(nodejs)环境搭建

1.同样的进入官网下载ui项目,项目在github中的位置:GitHub:Swagger-ui若github也无法访问详见最后文件下载地址。

2.下载到本地进行解压,首先看目录结构你可能会懵逼,不要紧,主体部分都放入dist目录下,可以进入dist目录打开index.html看下界面,可以发现基本的模式还是有了,只不过是静态的文件,接下来进行nodejs配置,使其可以进行端口访问,直接使用node命令访问index.js没有反应,英语稍微好点点的同学可以看下官网的配置步骤,接下来手动配置ui环境。

3.下面进行项目的配置,新建node_app文件夹,初始化node,输入好信息后会自动创建package.json文件,如下图:

初始化命令npm init,出现如下信息,填的地方可以随便写,也可以不写

4.将下载的swagger-ui中的dist文件夹拷贝到node_app下:

5.安装express,如果出错可以去nodejs安装目录进行安装

6.创建index.js,并将如下代码写入该js中

var express = require('express');
var app = express();
app.use('/root', express.static('dist'));
app.get('/', function (req, res) {
  res.send('Hello World!');
});

app.listen(3000, function () {
  console.log('Example app listening on port 3000!');
});

7.然后启动,并运行查看,如上代码为3000端口,如有冲突请自行修改

8.有些同学可能会懵逼:这个Uber API怎么来的呢?下面我再给您解释下这个Uber API的来路,编辑index.html

文件你会发现有一段url引用了swagger官网的jsonApi文件,这里我们将这个json文件下载下来放到和index.html平级

的目录,这里呢我直接访问我已经安装好的swagger-edtior进行文件的下载

然后存放到如下目录,并修改index.html

那么这个意思呢就是指我们在swagger-editor中编写好了api文档,我们再放到ui中去预览,那么到此swagger-editor

和swagger-ui已经部署完毕了,我也是一头雾水过来的,这位简书朋友给了我很大的帮助。


三、swagger-ui扩展版(tomcat)环境搭建

1.在SosoApi下载Swagger-ui扩展版,那SosoApi本身自己可以管理项目,编写API文档

2.解压后放入tomcat的webapps下,会java的同学就不用多说啦,开启服务器访问

  http://localhost:8080/SwaggerUI/,同样的将index.html中的json路径换成自己本地的路径

Json文件夹下存放的是编写好的Api模板,可以在头部进行搜索访问更换json

那么接下来的学习工作就得交给大家了,有很多知识我也是通过网络学习过来的接触也不是很长时间。


安装项目资源文件:http://download.csdn.net/detail/ron03129596/9707570


有不对的地方忘朋友们指出,及时更正,谢谢



用PicoContainer和Nanning实现事务管理

用PicoContainer和Nanning实现事务管理Transaction Manager, with PicoContainer and Nanning作者:冰云Blog:http://icec...
  • icecloud
  • icecloud
  • 2004-02-25 10:31:00
  • 2468

SwaggerUI+SpringMVC——构建RestFul API的可视化界面

SwaggerUI RESTFUL API。 我们都知道,接口文档是非常重要的,但是随着代码的不断更新,文档却很难持续跟着更新,今天要介绍的工具,完美的解决了这个问题。而且,对于要使用我们接口的人来说...
  • lbq613613
  • lbq613613
  • 2015-08-10 15:24:19
  • 6773

Node.js +Swagger Editor + Swagger-UI 环境搭建

安装node.js下载node.js最新版 https://nodejs.org/en/download/ 点击 安装器 node-v6.11.1.pkg 开始安装 一路下一步,安装完成 no...
  • ruglcc
  • ruglcc
  • 2017-07-26 22:02:39
  • 3295

Swagger 自定义UI界面

Swagger 自定义UI界面 Swagger简单介绍 如何使用Swagger 添加自定义UI界面 使用swagger-ui-layer...
  • tuposky
  • tuposky
  • 2017-09-13 14:11:48
  • 10847

swagger-ui教程 构建api接口文档工具

swagger swagger_ui
  • machihaoyu
  • machihaoyu
  • 2017-11-08 10:23:56
  • 154

SwaggerUI+SpringMVC-构建RestFul API的可视化界面

基于REST的API测试/文档类插件
  • quwenzhe
  • quwenzhe
  • 2016-04-06 14:37:44
  • 3524

app后端开发一:swagger-ui教程-构建api接口文档工具

声明之前写过关于app后端开发的一系列文章,那是我第一次做app后端开发,存在很多不足,本想好好修改一下,想想还是重新写吧,这样子也能让我博客文章看起来多一点嘛,万一以后找工作,别人一看我博客这么多内...
  • hel12he
  • hel12he
  • 2015-06-18 14:40:52
  • 39870

SwaggerUI+SpringMVC——构建RestFulAPI的可视化界面

今天给大家介绍一款工具,这个工具目前可预见的好处是:自动维护最新的接口文档。  我们都知道,接口文档是非常重要的,但是随着代码的不断更新,文档却很难持续跟着更新,今天要介绍的工具,完美的解决了这个问...
  • gebitan505
  • gebitan505
  • 2016-06-13 17:13:41
  • 12172

SpringMVC+Swagger UI生成可视图的API文档(详细图解)

SpringMVC+Swagger生成文档详细图解,以及遇到的异常处理
  • u011499992
  • u011499992
  • 2016-12-04 19:16:28
  • 32340

Thinkphp下搭建Swagger UI

作为后台开发人员,总是避免不了要给APP写API接口文档,之前都是用HTML5和CSS3+Jqury去写动态页面,但是每次修改的时候很麻烦,而且有可能改完代码忘记修改文档,所以就在网上找了些资料,发现...
  • dongrideyoushang
  • dongrideyoushang
  • 2016-10-28 10:53:40
  • 1749
收藏助手
不良信息举报
您举报文章:swagger环境的搭建(swagger-editor|swagger-ui)
举报原因:
原因补充:

(最多只允许输入30个字)