根据查询参数的存在打开 API 架构条件响应字段

Question

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

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

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

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

现在，当且仅当 total_documents 查询参数存在于 URL.

中时，我希望 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.'
                }
            }

这里的出路是什么？

谢谢，普拉迪普

Answer 1

JSON 模式没有请求或响应或 HTTP 的概念。

您这里有一份 OpenAPI 规范文档。

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

Runtime expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by Link Objects and Callback Objects.

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

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

根据查询参数的存在打开 API 架构条件响应字段

Open API schema conditional response field based on the presence of a query parameter

jsonschema

json-schema-validator

fastify