zoukankan      html  css  js  c++  java
  • 转:swagger 入门

    前言

    • 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 请求


    作者:Damonwong
    链接:http://www.jianshu.com/p/d6626e6bd72c
    來源:简书
    著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。
  • 相关阅读:
    程序员:不要自称为码农
    SpringBoot对静态资源配置
    LeetCode 572. Subtree of Another Tree(子树)
    LeetCode 437. Path Sum III(统计路径和等于sum的路径数量)
    LeetCode 112. Path Sum(判断路径和是否等于一个数)
    LeetCode 617. Merge Two Binary Trees(归并两棵二叉树)
    LeetCode 226. Invert Binary Tree(翻转二叉树)
    Failure to transfer org.apache.maven.plugins:maven-resources-plugin:pom:2.6 的解决办法
    linux-查询某软件的安装的目录
    WebService概念解释
  • 原文地址:https://www.cnblogs.com/xuyatao/p/7234097.html
Copyright © 2011-2022 走看看