基于查询参数的存在开放 API 模式条件响应字段答案

【问题标题】：Open API schema conditional response field based on the presence of a query parameter基于查询参数的存在开放 API 模式条件响应字段
【发布时间】：2021-08-13 04:42:52
【问题描述】：

我正在努力提供一个 GET REST API，我希望在其中有条件地包含 total_documents 字段（它是数据库表中存在的记录总数的整数计数）。

API 签名和响应负载将类似于：

    GET /endpoint/?total_documents&.....

    Response Payload:
    {
         documents: [....],
         total_documents: 100
    }

现在，当且仅当 URL 中存在 total_documents 查询参数时，我希望 total_documents 字段出现在响应负载中。

这是我尝试过的，基于我的架构：

 fastify.addSchema({
        $id: 'persistence-query-params',
        title: "PersistenceQueryParams",
        type: 'object',
        description: 'Persistence Service GET API URL query specification. Applicable for GET API only.',
        properties: {
            'total_documents': {
                description: 'Total number of documents present in the collection, after applying filters, if any. This query paramater does not take any value, just pass it as the name (e.g. &total_documents).',
                nullable: true,
            },
        },       
}

querystring: {
                description: 'Persistence Service GET API URL query specification. Applicable for GET API only.',
                $ref: 'persistence-query-params#',
            },
            response: {
                200: {
                    properties: {
                        'documents': {
                            description: 'All the retrieved document(s) from the specified collection for the specified service database and account.',
                            type: 'array',
                            items: {
                                $ref: 'persistence-response-doc#',                  
                            }
                        },
                        'total_documents': {
                            description: "If total_documents query paremeter is specified, gives the total number of documents present in the collection, after applying query paramaters, if any. If total_documents is not specified, this field will not be available in the response payload.",
                            type: 'number',
                            default: -1,
                        },
                    },
                    dependencies: {
                      'total_documents': { required: ['querystring/properties/total_documents'] },
                    },
                },
                '4xx': {
                    $ref: 'error-response#',
                    description: 'Error response.'
                }
            }

这里的出路是什么？

谢谢，普拉迪普

【问题讨论】：

标签： jsonschema json-schema-validator fastify

【解决方案1】：

JSON Schema 没有请求、响应或 HTTP 的概念。

这里有一份 OpenAPI 规范文档。

OpenAPI 规范定义了一种访问动态值的方法，但仅限于链接对象或回调对象中，其中包括查询参数。

运行时表达式允许根据以下信息定义值仅在实际 API 调用中的 HTTP 消息中可用。链接对象和回调对象使用此机制。

https://spec.openapis.org/oas/v3.1.0#runtime-expressions

JSON Schem 无法引用实例数据，更不用说与它不知道的上下文相关的数据了。

【讨论】：