文档章节

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

 易达
发布于 2016/10/15 20:06
字数 1463
阅读 1.3K
收藏 5

前言

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。好吧,以上是官方的说法,我直接复制的,在我看来swagger就是一个接口文档管理器,以前我们写接口一般都是world编写,但是有一个问题就是测试的时候需要依赖第三方工具,GET的接口还好,直接浏览器打开,POST的只能依赖另外的工具了,而Swagger呢,可以直接通过代码中的注解生成接口文档(JavaEE),一般人都用这种方式,而且直接集成在项目中,方便成员查看,同时还能直接测试,另外Swagger的界面也不错,也许这就是我选择用Swagger的原因吧,直接官方说的RESTful 风格那个不用管,不是RESTful 风格的接口也能用,当然Swagger还有一种方式就是手动写接口说明了,这样的好处就是代码只有代码,因为一旦代码中添加了Swagger的接口注解后,代码量还是增加了不少,当然坏处就是你改完了代码,还要去改接口文档,而本文主要介绍第二种方式

关键点

Swagger-UI

Swagger-edit在线版

Swagger-edit

Swagger-UI

其实就是静态的HTML、js、css文件,从github上下载下来,打开dist目录下的index.html,就能从运行起来了,不过默认是swwager demo的接口文档,如下图: 效果图Swagger主要通过json文件来实现接口文档和接口说明等功能,所以我们在输入框内输入不同的json地址,就能打开不同的接口文档

swagger-editor在线版

其实就是一个在线编辑接口文档的网页,刚才说过,Swagger-ui展示出来的接口完全依赖于的json的内容,所以我们可以通过Swagger-edit在线版来定制json的内容,不用自己写json,当然Swagger-edit在线版也是通过yaml 标记语言来的,不过看一下demo,就会很容易学会,编写完成后我们可以下载json文件到本地,供Swagger-ui使用,不过由于某种不为人知的原因,Swagger-edit在线版的访问速度那叫一个慢,所以一般我们都会下载Swagger-Edit在本地来运行

swagger-editor

这个和Swagger-edit在线版是同一个东西,不过因为在线版的速度太慢,所以我们需要在本地来运行一个Swagger-edit,这样就不存在网络卡等问题了

开始部署

下载相关文件

1、下载Swagger-UI

Swagger-UI,直接通过git clone或者下载zip都可以,使用到核心的东西就是下载下来的dist文件夹里面的东西

2、下载swagger-editor

这一步不是必要的,如果你不想用默认在线版的,就可以执行这一步,当然目前除了Swagger默认提供了一个在线的编辑器,还有第三方的,如sosoapi,全中文傻瓜式操作的,上手快速

下载时建议下载最新版的编译后的包,在swagger-editor页面中有说明当前最新的版本号和下载地址

3、下载和安装nodejs

这一步就不详细说了,到处都是教程,而且就算没有教程,相信对于程序员来说安装一个软件也是轻而易举的事情,如果不想用这个,可以直接跳过,查看tomcat运行swagger-editor

4、安装http-server

使用node.js安装http-server模块,主要通过http-server模块来启用http服务,运行swagger-editor,通过命令

npm install -g http-server  

不过由于某些原因,国内安装可能会非常慢,这时候我们就可以用淘宝 NPM 镜像,来加速 首先运行命令

npm install -g cnpm --registry=https://registry.npm.taobao.org  

然后可能需要重启cmd命令工具,运行

cnpm install -g http-server  

这样就能很快的安装http-server了,同样的道理,如果需要安装其他模块,也可以通过cnpm来安装,然后通过cmd命令进入到Swagger-edit的根目录,运行命令

http-server -p 8000  

-p的作用是指定端口,后面的8000就是我们指定的端口,访问localhost:8000就可以进入swagger-edit就可以进入编辑界面了,左边是编辑框,右边是预览界面,如下图 效果图 当然这一步也不是必须的,如果不愿用通过http-server来运行swagger-editor,可以通过tomcat来运行

tomcat运行swagger-editor

首先把swagger-editor目录复制到tomcat根目录的webapps,然后运行tomcat,访问localhost:8080/swagger-editor就可以了

5、导出json

由于编写接口文档并不在本文档的内容,所以关于编写这里就不多做描述,而且主要我觉得编写也没啥可说,直接跟着默认的接口文档来改就能看出来大概了,所以直接到最后一步,编写完成后导出json文件

点击File->DownLoad json就会下载swagger.json文件

6、部署swagger-ui

首先把json文件复制到swagger-ui根目录,修改index.html的引用json文件的url,最后直接打开index.html也行,部署到服务器也行,不过要注意index.html中引用的json文件的url一定要正确

结语

到此为止部署swagger的步骤已经完成了,如果有不明白或者不清楚的地方,可以留言交流

本文转载自:http://www.raye.wang/2016/09/29/swaggerhuan-jing-da-jian-zhi-fei-yi-lai-dai-ma-fa/

易达

粉丝 2
博文 31
码字总数 8263
作品 0
厦门
私信 提问
加载中

评论(0)

Swagger 搭建 API 文档管理平台

API 文档是前后端对接的基本,但如果还停留在手写文档的阶段,那就真的太 out 了。大家可能也尝试过各种 API 接口管理的工具,比如 postman 、apizza 等,但个人使用下来还是感觉麻烦了,长期...

BeckJin
2018/09/02
0
0
Restful形式接口文档生成之Swagger与SpringMVC整合手记

文章转载地址:http://javatech.wang/index.php/archives/74/ 笔者目前正在搭建一套API服务框架,考虑到客户端能够更方便的调用API服务(这里说的更方便是指避免不厌其烦地解说各接口需要的参...

北极之北
2016/04/01
1.4W
8
koa框架 mp2 node服务搭建swagger服务

说明:用koa2搭建静态文件服务器,mp2管理node服务,搭建swagger-ui和swagger-editor服务,项目地址:koa-swagger 1、环境搭建 安装最新版nodejs 新建文件夹koa-swagger,在文件夹内创建swa...

hkaikai
2018/07/04
752
0
用go-module作为包管理器搭建go的web服务器

本篇博客主要介绍了如何从零开始,使用Go Module作为依赖管理,基于Gin来一步一步搭建Go的Web服务器。并使用Endless来使服务器平滑重启,使用Swagger来自动生成Api文档。 源码在此处:项目源...

detectivehlh
2019/06/10
0
0
使用swagger实现web api在线接口文档

原文:使用swagger实现web api在线接口文档 一、前言   通常我们的项目会包含许多对外的接口,这些接口都需要文档化,标准的接口描述文档需要描述接口的地址、参数、返回值、备注等等;像我...

杰克.陈
2017/12/20
0
0

没有更多内容

加载失败,请刷新页面

加载更多

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

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

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

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

Venus_辉
4分钟前
7
0
恢复丢失的Joomla密码的最常用方法

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

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

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

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

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

TiDB
13分钟前
57
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部