api 文档那些事之swagger

时间 2019-11-21

标签 api 文档那些 swagger 繁體版

原文原文链接

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 UI 文件中dist 目录下的文件所有复制到 public 文件夹下。
启动： node index.js
打开浏览器，输入http://localhost:3000/static/index.html

编写文档并发布

能够用 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

这这个例子中，消费者把http://192.168.8.109:3000/api/person做为根节点来访问各类API

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 ############################################################################