仓库指标
- 星标
- (3,783 个星标)
- PR 合并指标
- (PR 指标待抓取)
描述
This is clearly an edge case, but I would still like to report it to gather feedback.
I keep finding this pattern:
openapi: 3.0.3
info:
title: Test API
description: "A test API"
version: 0.13.0-SNAPSHOT
paths:
/api/v1/users:
get:
summary: Retrieves a list of users
description: "Returns a list of all users"
responses:
"200":
description: List of users
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
components:
schemas:
List:
required:
- total
- items
type: object
properties:
kind:
type: string
items:
type: array
items:
type: object
total:
format: int32
description: Total number of entries in the full result set
type: integer
nullable: false
size:
format: int32
description: Number of entries per page (returned for fetch requests)
type: integer
page:
format: int32
description: Current page number (returned for fetch requests)
type: integer
UserList:
allOf:
- $ref: '#/components/schemas/List'
- description: List of users
type: object
properties:
items:
type: array
items:
type: string
The intention is clear, declare an abstract List and have concrete instances of it overwriting the items field.
It's pretty clearly not defined behavior, but I keep finding it in various places and it shows that, probably, OpenAPI tooling is handling this (most of those)cases according to the intention (as opposed to the spec).
Removing the items field from the "parent" produces the expected output.
Now, I'm not sure how to proceed here, should we fail instead of silently producing unusable code? Or should we handle this case(since is quite popular) with some kind of overwriting mechanism?