【技术】--swagger

【前言】

    小编在使用swagger去编写接口的时候，总是觉得有些不知道如何下手，之前参考swagger editor 去编写的，但是swagger editor提供的也就那么几个例子，不能完全满足咱们项目中的使用，之前一直忽略了swagger的规范，现在简单的总结的一下swagger 3.0的使用规范。

【正文】

    OpenAPI规范（OAS）为RESTful API定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，消费者可以用最少量的实现逻辑理解远程服务并与之交互。

文档生成工具可以使用OpenAPI定义来显示API，使用各种编程语言生成服务器和客户端的代码生成工具，测试工具以及许多其他用例。

数据类型

OAS中的原始数据类型基于JSON Schema Specification Wright Draft 00支持的类型。请注意，integer由于类型也受支持，并且被定义为没有分数或指数部分的JSON数字。 null不支持作为一种类型（请参阅nullable替代解决方案）。模型使用Schema对象来定义，该对象是JSON Schema Specification Wright Draft 00的扩展子集。

基元有一个可选的修饰符属性：format。OAS使用几种已知格式来详细定义所使用的数据类型。但是，为了支持文档需求，该format属性是一个公开string价值的属性，可以具有任何价值。即使本规范未定义，也可以使用诸如"email"，等的格式"uuid"。不带format属性的类型遵循JSON模式中的类型定义。没有把特定的formatMAY默认识别回来的工具，就type好像format没有指定。

OAS定义的格式是：

通用名称	type	format	注释
整数	integer	int32	签名32位
长	integer	int64	签名64位
浮动	number	float
双	number	double
串	string
字节	string	byte	base64编码的字符
二进制	string	binary	任何八位字节的序列
布尔	boolean
日期	string	date	正如定义full-date- RFC3339
约会时间	string	date-time	正如定义date-time- RFC3339
密码	string	password	提示UI以隐藏输入。

服务器变量对象

代表服务器URL模板替换的服务器变量的对象。

固定字段

字段名称	类型	描述
枚举	[string]	如果替换选项来自有限集合，则使用字符串值的枚举。
默认	string	需要。用于替换的默认值，如果未提供替代值，则发送。与模式对象 不同default，这个值必须由消费者提供。
描述	string	服务器变量的可选描述。CommonMark语法可用于富文本表示。

这个对象可以扩展为规范扩展。

组件对象

为OAS的不同方面保存一组可重用的对象。在组件对象中定义的所有对象都不会影响API，除非它们是从组件对象之外的属性显式引用的。

固定字段

字段名称	类型	描述
模式	地图[ string，模式对象 | 参考对象 ]	一个持有可重用架构对象的对象。
回复	映射[ string，响应对象 | 参考对象 ]	一个对象来保存可重用的响应对象。
参数	映射[ string，参数对象 | 参考对象 ]	一个对象来保存可重用的参数对象。
例子	映射[ string，示例对象 | 参考对象 ]	一个对象来保存可重用的示例对象。
requestBodies	映射[ string，请求正文对象 | 参考对象 ]	一个持有可重用的请求正文对象的对象。
头	Map [ string，Header Object | 参考对象 ]	一个对象来保存可重用的标题对象。
securitySchemes	Map [ string，安全方案对象 | 参考对象 ]	一个持有可重用安全方案对象的对象。
链接	地图[ string，链接对象 | 参考对象 ]	一个持有可重用的链接对象的对象。
回调	Map [ string，回调对象 | 参考对象 ]	一个持有可重用回调对象的对象。

这个对象可以扩展为规范扩展。

上面声明的所有固定字段都是必须使用与正则表达式匹配的键的对象^[a-zA-Z0-9\.\-_]+$。

字段名称示例：

User
User_1
User_Name
user-name
my.org.User

组件对象示例

"components": {
  "schemas": {
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "http://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}

【总结】
     知其然更要知其所以然。