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

TeelaFlo42 8年前

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

前言

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

        总结一句话就是好用，逼格高。下面我将总结一下如何快速在本地搭建一个基于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 在本地配置好了。当然你也可以吧这个搭建在服务器上

        编写文档并发布