Swagger UI教程 API 文档神器 搭配Node使用

API   2016-01-22 16:54:10 发布
您的评价:
     
0.0
收藏     0收藏
文件夹
标签
(多个标签用逗号分隔)

在团队开发中,一个好的 API 文档可以减少很多 交流成本 ,也可以使一个新人快速上手业务。

前言

  • swagger ui 是一个API在线文档生成和测试的利器,目前发现最好用的。
  • 为什么好用? Demo 传送门
    • 支持API自动生成同步的在线文档
      • 这些文档可用于项目内部API审核
      • 方便测试人员了解API
    • 这些文档可作为客户产品文档的一部分进行发布
      • 支持API规范生成代码,生成的客户端和服务器端骨架代码可以加速开发和测试速度

总结一句话就是好用,逼格高。下面我将总结一下如何快速在本地搭建一个基于Node和Swagger UI的 API 的文档工具

环境搭建

  • 下载Swagger UI(也可以直接下载 zip 文件)
git clone https://github.com/swagger-api/swagger-ui.git
  • 安装 express
  • 创建一个空文件夹 node_app
mkdir node_app
  • 初始化 node ,创建package.json文件()
➜  ~ ✗ >cd node_ap
➜  ~/node_app ✗ >npm init
// 下面的看你心情填写
name: (node_app) node_app
version: (1.0.0)
description:
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)
  • 安装 express
➜ ~/node_app git:(master) ✗ >npm install express --save
  • 创建 index.js
➜  ~/node_app git:(master) ✗ >vim index.js
  • 把下面代码贴如 index.js 中
var express = require('express');
var app = express();
app.get('/', function (req, res) {
  res.send('Hello World!');
});

app.listen(3000, function () {
  console.log('Example app listening on port 3000!');
});
  • 在 node_app 中创建空目录 public
➜  ~/node_app git:(master) ✗ >mkdir public
➜  ~/node_app git:(master) ✗ >cd public
  • 修改路由
    ➜  ~/node_app/public git:(master) ✗ >vim ../index.js
    //在文件第三行插入下面这句话
    app.use('/static', express.static('public'));
  • 把下载好的Swagger UI 文件中dist 目录下的文件全部复制到 public 文件夹下。
    目录结构
  • 开启 node
    ➜  ~/node_app git:(master) ✗ >node index.js
  • 打开浏览器,输入 http://localhost:3000/static/index.html

到此为止,你已经把官方的 demo 在本地配置好了。当然你也可以吧这个搭建在服务器上

编写文档并发布

  • 使用 Swagger Editor 编写 API 文档
    • Swagger Editor 上的是基于 yaml 的语法,但是不用害怕,看着官方的 demo 看个10分钟就会了。
  • 导出 test.json 文档
    导出方式
  • 把 test.json 放到 node_app/public 目录下。
  • 利用编辑器修改 url = "http://petstore.swagger.io/v2/swagger.json"; 为 url = "/static/test.json";
  • 重启 node 服务,浏览器中打开 http://localhost:3000/static/index.html 就是你自己写的 api 文档了

效果图

自己写的 API 接口

PUT请求
GET请求
POST 请求
DELETE 请求

来自: http://www.jianshu.com/p/d6626e6bd72c

扩展阅读

一份旨在帮助 Android 初学者快速入门以及找到适合自己学习的资料
使用 Swagger UI 与 Swashbuckle 创建 RESTful Web API 帮助文件
基于beego创建Restful风格的API项目及API文档自动化
Spring3 MVC中使用Swagger生成API文档
以开发者的视角整理编排的前端开发所使用语言的主流学习资源

为您推荐

hackathon-starter - A boilerplate for Node.js web applications
抛开 React 学习 React 第二部分
react+reflux入门教程
AngularJS的增删改查、state嵌套案例,不涉及服务端
史上最全 前端开发面试问题及答案整理

更多

API
Node.js 开发
相关文档  — 更多
相关经验  — 更多
相关讨论  — 更多