api 文档那些事之swagger

原创
2017/11/08 15:45
阅读数 460

nodejs 搭载 swagger

  • swagger ui是一个API在线文档生成和测试的利器,目前发现最好用的。

环境搭建

  • 下载swagger ui
git clone https://github.com/swagger-api/swagger-ui.git
  • 创建一个空文件夹 node_app
npm init (生成package.json文件)

name: (node_app) node_app
version: (1.0.0)
description:
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)

  • 安装 express
npm install express --save
  • 创建index.js
var express = require('express');
var app = express();
app.use('/static', express.static('public'));
app.get('/api/person', function (req, res) { //返回的数据类型和url路径要一至
  res.send([{
    "firstName": "s",
    "lastName": "s",
    "userName": "d"
  }]);
});


app.listen(3000, function () {
  console.log('Example app listening on port 3000!');
});


编写文档并发布

  • 可以用 Swagger Editor 编写API文档
  • Swagger Editor 上的是基于 yaml 的语法
  • 编写好以后下载json文件 输入图片说明
  • 把swagger.json放到public文件下面
  • 修改public文件下index.html页面 输入图片说明
  • 重新启动node index.html 和刷新页面就可以了

编写api 文档从零开始学习地址参考:Swagger从入门到精通

  • 1.最简单的例子
swagger: "2.0"

info:
 version: 1.0.0
 title: Simple API
 description: A simple API to learn how to write OpenAPI Specification

schemes:
 - https
 - http
host: 192.168.8.109:3000
basePath: /api

paths: {}
  • 1.1 OpenAPI规范的版本号
    • 首先我们要通过一个swagger属性来声明OpenAPI规范的版本。
swagger: "2.0"
  • 1.2 API描述信息
    • 然后我们需要说明一下API文档的相关信息,比如API文档版本(注意不同于上面的规范版本)、API文档名称已经可选的描述信息。
info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification
  • 1.3 API的URL
    • 作为web API,一个很重要的信息就是用来给消费者使用的根URL,可以用协议(http或者https)、主机名、根路径来描述:
schemes:
  - https
host: simple.api
basePath: /openapi101

2. 定义一个API操作

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https
  - http
host: 192.168.8.109:3000
basePath: /api

paths: 
  /person:
    get:
      summary: Gets some persons
      description: Returns a list containing all 
      responses:
        200:
          description:  A list of Person
          schema:
            type: array
            items:
              required: 
                - username
              properties:
                firstName:
                  type: string
                lastName: 
                  type: string
                userName:
                  type: string
  • 如图:

输入图片说明

  • 2.1 添加一个路径(path)
    • 我们添加一个/persons的路径,用来访问一组用户信息:
paths:
  /persons:
  • 2.2 在路径中添加一个HTTP方法(get,post,put,delete)
    • 比如需要展示一组用户信息,我们可以在/persons路径中添加get方法,同时还可以填写一些简单的描述信息(summary)或者说明该方法的一段长篇大论(description)
   get:
      summary: Gets some persons
      description: Returns a list containing all persons.
  • 2.3 定义响应(response)类型(返回状态码200,404,304,500等)
  responses:
        200:
          description: A list of Person
  • 2.4 定义响应内容
    • 通过响应消息中的模式(schema)属性来描述清楚具体的返回内容。
    • 一组用户信息就是一个用户信息对象的数组(array),每一个数组元素则是一个用户信息对象(object),该对象包含三个string类型的属性:姓氏、名字、用户名,其中用户名必须提供(required)。
 schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string
  • 3.1 定义请求参数(query parameters)
   #START############################################################################
      parameters:
       - name: pageSize
         in: query
         description: 要传入每一页面大小
         type: number
       - name: pageNumber
         in: query
         description: 要传入的分页数量
         type: number
      # END ############################################################################


    完整的类型
    swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https
  - http
host: 192.168.8.109
basePath: /index

paths: 
  /person:
    get:
      summary: Gets some persons
      description: Returns a list containing all
      #START############################################################################
      parameters:
       - name: pageSize
         in: query
         description: 要传入每一页面大小
         type: number
       - name: pageNumber
         in: query
         description: 要传入的分页数量
         type: number
      # END ############################################################################   
      responses:
        200:
          description:  A list of Person
          schema:
            type: array
            items:
              required: 
                - username
              properties:
                firstName:
                  type: string
                lastName: 
                  type: string
                userName:
                  type: string

通过 get /persons?pageSize=20&pageNumber=2 来访问第2页的用户信息(不超过20条)

  • 3.1 在get方法中增加请求参数
paths:
  /persons:
    get:
      summary: Gets some persons
      description: Returns a list containing all persons. The list supports paging.
#START############################################################################
      parameters:
# END ##############################
  • 3.2 添加一个 get /persons/{username} 操作
swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https
host: simple.api
basePath: /openapi101

paths:
  /persons:
                username:
                  type: string
#START############################################################################
  /persons/{username}:
    get:
      summary: Gets a person
      description: Returns a single person for its username
# END ############################################################################
展开阅读全文
加载中

作者的其它热门文章

打赏
0
0 收藏
分享
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部