Замените модель в схеме openapi внешним значением Rust во время генерации

В конечном итоге это решение, которое работает для меня. Я все равно был бы очень признателен за точку зрения на общую проблему от кого-то, кто делал это раньше. Документация расплывчата до такой степени, что вводит в заблуждение по ряду ее аспектов, и ни один результат поиска, который я смог найти, не достиг уровня полного описания решения. У меня до сих пор много вопросов, например: «Действительно ли это так и должно быть сделано?» Я надеюсь, что любой, кому предстоит решить ту же проблему, немедленно найдет этот ответ и найдет его полезным, а не разочарованием, которое я испытал.

В любом случае, моя схема OpenAPI была структурирована следующим образом.

├── openapi.yaml
├── parameters
│   ├── path
│   └── query
├── path_items
│   ├── things.yaml
└── schemas
    ├── errors
    └── responses

где схема, которую я хотел преобразовать в импорт типа из внешнего ящика, ссылалась на путь через:

# path_items/things.yaml
get:
  operationId: GetThingsPage
  description: Get a single page of things.
  security:
    - ThingsAuth:
        - things:read
  parameters:
    - $ref: "../parameters/path/thing_id.yaml"
    - $ref: "../parameters/query/user.yaml"
    - $ref: "../parameters/query/page_token.yaml"
  responses:
    200:
      description: OK
      content:
        application/json:
          schema:
            $ref: "../schemas/responses/getthingspageresponse.yaml"
    400:
      description: BAD_REQUEST
      content:
        application/json:
          schema:
            $ref: "../schemas/errors/error.yaml"
    401:
      description: UNAUTHORIZED
      content:
        application/json:
          schema:
            $ref: "../schemas/errors/error.yaml"
    403:
      description: FORBIDDEN
      content:
        application/json:
          schema:
            $ref: "../schemas/errors/error.yaml"
    500:
      description: INTERNAL_SERVER_ERROR
      content:
        application/json:
          schema:
            $ref: "../schemas/errors/error.yaml"

# schemas/responses/getthingspageresponse.yaml
type: object
properties:
  next_page_token:
    name: next_page_token
    type: string
    description: |
      If present, used to fetch the next set of results, otherwise it's the last page.
  things:
    description: Page of things.
    type: array
    items:
      $ref: "../../openapi.yaml#/components/schemas/Thing"
required:
  - things

и наконец,

# openapi.yaml
components:
  schemas:
    Thing:
      # All of the different ways I tried to express that this is
      # a "placeholder," intended to be specified in some mapping option
      # as an import.

То, что сначала попало в шкаф, было

# openapi.yaml
components:
  schemas:
    Thing:
      description: A reference to `Thing` as defined in our global models.
      type: ExternalThingSchema

а затем typeMapping (в конфигурации, передаваемой в CLI с опцией -c):

packageName: "things-internal-server"
skipSchemaValidation: true
additionalProperties:
  generateAliasAsModel: true
typeMappings:
  ExternalThingSchema: "the_crate::models::Thing"

В результате был создан код Rust, который наконец осознал мою внешнюю зависимость:

/// A reference to `Thing` as defined in our global models.
#[derive(Debug, Clone, PartialEq, PartialOrd, serde::Serialize, serde::Deserialize)]
#[cfg_attr(feature = "conversion", derive(frunk::LabelledGeneric))]
pub struct Thing(the_crate::models::Thing);

Но наличие этой оболочки newtype раздражает, поэтому я подумал о том, чтобы переместить внешний тип непосредственно в тело ответа:

# schemas/responses/getthingspageresponse.yaml
type: object
properties:
  next_page_token:
    type: string
    description: |
      If present, used to fetch the next set of results, otherwise it's the last page.
  things:
    description: Page of things.
    type: array
    items:
      description: A reference to `Thing` as defined in our global models.
      type: ExternalThingSchema
required:
  - things

Это не работает: генератор сообщает, что «[main] ERROR o.o.codegen.utils.ModelUtils - Undefined array inner type for 'null'. Default to String», а в журналах debugModel мы видим, что назначенный тип — это Vec<String>.

Итак, в конце концов кажется (и я не могу сказать почему), что ExternalThingSchema можно упомянуть только в файле openapi.yaml верхнего уровня:

components:
  schemas:
    GetThingsPageResponseBody:
      type: object
      properties:
        next_page_token:
          description:  If present, used to fetch the next set of results, otherwise it's the last page.
          type: string
        things:
          description: Page of things.
          type: array
          items:
            description: A reference to `Thing` as defined in our global models.
            type: ExternalThingSchema
      required:
        - things

производит

#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, validator::Validate)]
#[cfg_attr(feature = "conversion", derive(frunk::LabelledGeneric))]
pub struct GetThingsPageResponseBody {
/// If present, used to fetch the next set of results, otherwise it's the last page.
    #[serde(rename = "next_page_token")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub next_page_token: Option<String>,

/// Page of things.
    #[serde(rename = "things")]
    pub things: Vec<the_crate::models::Thing>,

}

наконец-то это то, чего я хотел.

NB: Даже с этим typeMappings, и хотя он генерирует то, что я хочу, генератор все равно выдает предупреждения:

[main] WARN  o.o.codegen.DefaultCodegen - Unknown type found in the schema: ExternalThingSchema. To map it, please use the schema mapping option (e.g. --schema-mappings in CLI)

Передача всего возможного schemaMappings не имеет никакого эффекта, и меня это не волнует.