使用Swagger/OpenAPI扩展JSON元数据

我正在寻找一种方法来声明使用Swagger/OpenAPI（或类似的，如果有另一种格式支持请求的功能）指定的API中使用的JSON对象的扩展元数据。使用Swagger/OpenAPI扩展JSON元数据

这个想法是使用这个元数据来自动/部分地生成用户界面来编辑这些数据。

的要求的功能列表：

像名用户可读信息，说明，占位符，例子多语言支持 - 名称和 API规范的描述本身可能比什么不同最终用户例如CRUD编辑器应该看到。
验证元数据
我知道，像最小值，最大值，模式等在那里一扬鞭各个领域/ OpenAPI的 - 但有没有办法指定验证特定的（多语种）的错误信息（喜欢的东西“A用户名必须由字母和数字组成“以及翻译成多种语言）。或者需要匹配的多个模式（每个错误消息与相连）。

验证的另一种方法可能是对自己的API调用（如的检查，如果电子邮件或用户名可用）
关系的元数据例如，该ID字段实际上referes到另一个人的ID 对象（具有其自己的元数据）。

来源

2016-04-11 Fionn

的所述OpenAPI（FKA。扬鞭）规范可以通过使用x-特性被扩展（参见Specification Extension是规范）。这些x-属性被标准的OpenAPI解析器忽略。

即使在JSON模式定义中，您也可以在规范文件的几乎任何位置定义属性，但是您必须编写自己的解析器来使用它们和/或修改Swagger UI之类的工具（这很容易做）看到他们在这样的工具。

下面是在定义的一些X-紧张的例子：

swagger: "2.0" 

info: 
    version: 1.0.0 
    title: X-tension example 
    description: Using x- properties to extend the OpenAPI specification 
    x-example: we can put x-tension almost anywhere in the specification 

paths: {} 

definitions: 
    User: 
    properties: 
     id: 
     type: string 
     name: 
     type: string 
     maxLength: 50 
     minLength: 10 
     x-validation: 
      multiLingualMessage: 
      en: Name's length must be between <minLength> and <maxLength> 
      fr: La longeur de Name doit être comprise entre <minLength> et <maxLength> 
     friends: 
     type: array 
     description: An array of UserId 
     items: 
      type: string 
      x-reference: 
      type: User

这OpenAPI的规范是由编辑视为有效：它忽略了x-性能。

此示例仅为x-属性的说明，并不打算解决问题中列出的所有用例。

来源

2016-07-02 18:40:21

使用Swagger/OpenAPI扩展JSON元数据

回答

相关问题