zoukankan      html  css  js  c++  java
  • Swagger UI教程 API 文档神器 搭配Node使用

    在团队开发中,一个好的 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 请求
  • 相关阅读:
    POJ-2253 Frogger dijsktra查找间隔最小的路径
    LightOJ-1282 Leading and Trailing 模算数 快速幂 对数的用法
    LightOJ-1341 Aladdin and the Flying Carpet 分解质因数(注意对大素数的优化)
    UVA-10200 Prime Time 素数(注意除法精度)
    POJ-2142 The Balance 扩展欧几里德(+绝对值和最小化)
    ArchLinux 音乐播放客户端ncmpcpp和服务端mpd的配置
    [笔记-统计学习方法]感知机模型(perceptron) 原理与实现
    [Bug]Python3.x AttributeError: libtest.so: undefined symbol: fact
    [Bug]C++ XXX:undefined reference to "xxx"
    ip代理池的爬虫编写、验证和维护
  • 原文地址:https://www.cnblogs.com/zzsdream/p/6895893.html
Copyright © 2011-2022 走看看