标签: openapi

我想通过我的API从我的数据库中请求一个表.但是,我不知道该表将包含多少列,或者它将包含哪些列.如何在Swagger中指定它？这就是我想做的事情:

paths:
  /reports/{id}:
    get:
      summary: Detailed results
      description: filler
      parameters:
        - name: id
          in: path
          description: filler
          required: true
          type: integer
          format: int64
      responses:
        200:
          description: OK
          schema:
            type: array
            items: 
              $ref: '#/definitions/DynamicObject'
definitions:
  DynamicObject:
    type: object
    properties:
      **$IDONTKNOWWHATTODO**

关于如何定义没有特定参数的JSON对象的任何想法？

问题陈述：

出于“奇怪”的原因，我们对一个 API 的所有操作都有不同的“主机”。我们有这样的 API：

• 操作 1：获取 https://host1:port1/api/resources
• 操作 2：获取 https://host1:port2/api/resources/{id}
• 操作 3：POST https://host2:port3/api/resources
• 操作 4：POST https://host2:port4/api/resources/search

如果我们照原样使用 Swagger/OpenAPI，就意味着每个操作创建一个 Swagger/OpenAPI 规范，导致每个操作有一个 swagger-ui 页面，然后，需要重新创建一个索引页面来列出一个操作的所有操作API :-/ 这正是我们想要避免的。

问题：

1/ 这个特性——在“/{path}”级别覆盖“host”和“basePath”——有意义吗？

2/ 是否有人已经尝试在 swagger-ui 中实现此功能？

3/ 我可以/应该建议对 OpenAPI 进行这种更改吗？

欢迎任何其他有用的评论/评论;-)

对于客户端，这是在 client.yaml 中

/clients:
    get:
      tags:
      - "Clients"
      description: "List Clients The list capability"
      produces:
      - "application/json"
      parameters:
      - name: "tenantIdentifier"
        in: "query"
        required: true
        type: "array"
        items:
          type: "string"
          enum:
          - "default"
      responses:
        200:
          description: "successful operation"
        400:
          description: "Invalid status value"
      security:
      - basicAuth: []
    post:
      tags:
      - "Clients"
      summary: "Create client if address is enabled"
      description: ""
      operationId: "addClient"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "tenantIdentifier"
        in: "query"
        description: ""
        required: true
        type: "array" …

我在使用OpenAPI 3定义可重用的模式组件时遇到了麻烦,因为OpenAPI 3允许包含多种类型的数组.每个项类型都继承自同一父类,但具有特定的子属性.这似乎model在SwaggerHub 的视图中正常工作,但示例视图未正确显示数据.

TLDR; 有没有办法在OpenAPI 3中定义包含不同对象类型的数组？

Response:
  allOf:
    - $ref: '#/components/schemas/BaseResponse'
    - type: object
      title: A full response
      required:
      - things
      properties:
        things:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/ItemOne'
              - $ref: '#/components/schemas/ItemTwo'
              - $ref: '#/components/schemas/ItemThree'

我在 Symfony 4 Flex 应用程序中使用 API 平台 v2.2.5，包括一个带有JWT 身份验证的功能 API 、许多资源和可通过路由访问的默认Open API/Swagger 文档页面/api。根据库 docs，每个 API 资源都通过平台配置自动包含在文档中。

您如何为自定义操作（例如安全组件的身份验证路由）生成文档？该API平台文档似乎并没有包括这些指令。

我试图在此示例中为“房屋”添加一个只读字段。这房子是我想成为只读的另一种模型。

在此示例中，可以将Dogs数组设置为readOnly没有错误，但是当我将House的单一定义设置readOnly为时，在Swagger编辑器中会收到以下警告：

$ refs不允许同级值

我知道这是因为模型中的所有内容都在这里继承。那么，如何定义写API调用不能在此端点中定义“房屋”，同时又允许在另一个API端点中创建和更新房屋？

Pets:
  properties:
    id:
      type: string
      example: AAAAE12-1123AEF-1122312123
      readOnly: true
    name:
      type: string
      example: My Default Name
    text:
      type: string
      example: My Default Text
  Dogs:
    type: array
    readOnly: true
    items:
      $ref: '#/definitions/Dog'    
  House:
    readOnly: true
    $ref: '#/definitions/House'

我有以下 OpenAPI 定义：

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: now.httpbin.org
paths:
  /:
    get:
      summary: Get date in rfc2822 format
      responses:
        200:
          schema:
            type: object
            items:
              properties:
                now:
                  type: object
                    rfc2822:
                      type: string

我想rfc2822从响应中检索：

{"now": {"epoch": 1531932335.0632613, "slang_date": "today", "slang_time": "now", "iso8601": "2018-07-18T16:45:35.063261Z", "rfc2822": "Wed, 18 Jul 2018 16:45:35 GMT", "rfc3339": "2018-07-18T16:45:35.06Z"}, "urls": ["/", "/docs", "/when/:human-timestamp", "/parse/:machine-timestamp"]}  

但是当我从 Swagger Editor …

我正在使用 OpenAPI 3 并有两个查询参数，其中至少一个是必需的，但哪个无关紧要。

即，作为sudocode：

if parameter_1 OR parameter_2:
    do stuff
else:
    error

这在 OpenAPI 3 中可能吗？就我所见，规范或 JSON Schema 规范中都没有提及它。

我有基本的 Api，它接受默认的标头值my-api-key和相应的值。

我试图让 Swagger UI 允许我输入一次标题进行授权，并让键/值随每个请求一起传递。

到目前为止，我只成功地将标头作为参数显式添加到每个端点，但这并不理想。

相关代码片段：

        services.AddApiVersioning(
            options =>
            {
                // reporting api versions will return the headers "api-supported-versions" and "api-deprecated-versions"
                options.ReportApiVersions = true;
            });
        services.AddVersionedApiExplorer(
            options =>
            {
                // add the versioned api explorer, which also adds IApiVersionDescriptionProvider service
                // note: the specified format code will format the version as "'v'major[.minor][-status]"
                options.GroupNameFormat = "'v'VVV";

                // note: this option is only necessary when versioning by url segment. the SubstitutionFormat
                // can also be used to control …

我将我的 JSON 模式分成两个文件。

person-input.json （将由输入设置的所有属性。）

person.json （持有对 person-input.json 的引用，但也有 dateUpdate、dateCreated 和 DateDeleted）。

这将输入与自动生成的日期属性分开。

我不希望任何帖子能够向我的数据添加不需要的属性，所以我想我会使用"additionalProperties": false的问题是，如果我在person-input.json文件中使用它，它将不接受文件中的“日期”属性person.json。如果我把它放在 person.json 文件中，它不会阻止添加随机属性。这个问题有方法解决吗？

所以下面这个不起作用，我放错地方了"additionalProperties": false吗？

person.json

{
  "allOf": [
    {
      "$ref": "./person-input.json"
    },
    {
      "type": "object",
      "properties": {
        "dateCreated": {
        "name": "dateCreated",
        "type": "string",
        "description": "date created",
        "example": "2019-09-02T11:17:41.783Z"
        },
        "dateUpdated": {
          "type": "string",
          "nullable": true,
          "description": "date updated",
          "example": "2019-09-02T11:17:41.783Z"
        },
        "dateDeleted": {
          "type": "string",
          "nullable": true,
          "description": "date deleted",
          "example": "2019-09-02T11:17:41.783Z"
        }
      },
      "additionalProperties": false
    } …