Cómo Usar Discriminador para APIs: Tipos de Parámetros en Apidog

En nuestro artículo anterior "Qué hacer cuando una API tiene múltiples estructuras de parámetros", discutimos que cuando una API requiere diferentes estructuras de parámetros, puedes usar oneOf, anyOf o allOf en Apidog para definirlas.

Una vez que hayas configurado las estructuras de parámetros utilizando estas composiciones de esquema, y tus parámetros incluyan un campo que identifique el tipo de datos, puedes hacer la documentación aún más clara utilizando la característica discriminator de la especificación OpenAPI para distinguir entre los esquemas de manera más intuitiva.

¿Qué es Discriminator?

En OpenAPI, el papel de discriminator es implementar el "polimorfismo" de la programación orientada a objetos.

En pocas palabras, utiliza una propiedad compartida y su valor único para indicar claramente qué esquema específico de la lista oneOf o anyOf debe utilizarse.

Por ejemplo, en una tienda de mascotas, necesitamos usar un esquema para describir mascotas. (Y los gatos y perros tienen propiedades diferentes).

El esquema para perros es:

{

    "name": "Hotdog",

    "age": 3,

    "weight": 25.5,

    "petType": "dog",

    "breed": "Golden Retriever",

    "isVaccinated": true,

    "walkingSchedule": "Morning and Evening",

    "favoriteToys": ["Frisbee", "Tennis Ball"],

    "trainingLevel": "Intermediate"

}

El esquema para gatos es:

{

    "name": "Meow",

    "age": 2,

    "weight": 4.2,

    "petType": "cat",

    "isVaccinated": true,

    "isIndoor": true,

    "litterBoxType": "Enclosed",

    "scratchingPostHeight": 120,

    "favoriteSleepingSpot": "Balcony"

}

Como puedes ver, aunque ambos esquemas tienen campos comunes como petType, name, age, etc., los perros tienen campos específicos como breed, walkingSchedule, etc., mientras que los gatos tienen campos específicos como isIndoor, litterBoxType, etc.

Si solo usas oneOf para definir estos esquemas al diseñar la documentación de tu API, la documentación puede distinguir técnicamente entre los esquemas de perro y gato. Sin embargo, la correspondencia de cada tipo no es muy clara. Los lectores deben cambiar entre las dos pestañas de esquema para compararlos, lo que se vuelve confuso cuando hay muchos parámetros.

usar oneOf para definir múltiples esquemas

Al añadir un discriminator, la documentación mostrará un menú desplegable, donde los lectores pueden elegir el valor de petType (perro o gato). Una vez seleccionado, la página muestra automáticamente el esquema correcto con los campos relevantes. Esto elimina la necesidad de comparar múltiples pestañas y hace que las diferencias entre cada esquema sean mucho más claras.

discriminator haciendo los esquemas más claros

Un discriminator se usa típicamente junto con oneOf o anyOf. `oneOf` define los posibles esquemas de objeto, y el discriminator le dice al analizador cómo determinar qué esquema aplicar basándose en el tipo seleccionado.

Esto hace que los objetos complejos sean más claros y ayuda a las herramientas a distinguir automáticamente los tipos al renderizar la documentación o generar código.

Propiedades de configuración de `discriminator`

Un discriminator contiene dos propiedades clave:

propertyName: Especifica el nombre del campo utilizado para distinguir tipos, como petType en el ejemplo anterior.
mapping: Define la relación de mapeo entre los valores de campo y los esquemas específicos, como "dog" correspondiente al esquema de perro y "cat" correspondiente al esquema de gato.

Ejemplo de configuración en OpenAPI:

discriminator:
  propertyName: petType
  mapping:
    dog: '#/components/schemas/Dog'
    cat: '#/components/schemas/Cat'

Configuración de Discriminator en Apidog

Apidog soporta la configuración de discriminator de dos maneras:

GUI + JSON Schema
Importar las especificaciones OpenAPI directamente

Método 1: GUI + JSON Schema

Primero, crea los esquemas en Apidog, como Dog y Cat:

Abre el endpoint donde quieras usar estos esquemas y ve al editor del cuerpo de la solicitud o respuesta.

Selecciona el campo que deseas definir como una composición de esquema y elige Configuración Avanzada → Composiciones de Esquema → oneOf.

En oneOf, referencia los esquemas que necesites, como Dog y Cat.

referenciando los esquemas para composiciones de esquema oneOf

Ahora has definido múltiples esquemas posibles a través de oneOf. A continuación, debes añadir discriminator para especificar cómo distinguir estos esquemas. Haz clic en JSON Schema para cambiar al modo de código:

Añade la configuración de discriminator en la ubicación apropiada (al mismo nivel que oneOf), por ejemplo:

"discriminator": {
    "propertyName": "petType",
    "mapping": {
        "dog": "#/definitions/190704823",
        "cat": "#/definitions/190704706"
    }
}

Los valores en mapping, como #/definitions/190704823, son IDs únicos generados internamente por Apidog para los esquemas. Puedes encontrar la ruta definitions correspondiente para cada esquema en el panel de configuración de JSON Schema.

panel de configuración de JSON Schema en Apidog

Una vez completada la configuración, guárdala. En la documentación de la API, puedes cambiar inteligentemente los tipos de objeto basándote en el valor del campo petType.

Método 2: Importar las Especificaciones OpenAPI Directamente

Este es un enfoque más estándar, especialmente adecuado para equipos acostumbrados a flujos de trabajo de "diseño primero".

Escribe tus especificaciones OpenAPI con discriminator incluido, luego impórtalas en Apidog.

Por ejemplo, en las especificaciones OpenAPI, la definición de discriminator es la siguiente:

Pet:
  oneOf:
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Cat'
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      cat: '#/components/schemas/Cat'

Esta definición establece claramente:

A través de oneOf, especifica que el objeto podría ser de tipo Dog o Cat
A través de discriminator, especifica la determinación del tipo específico basándose en el valor del campo petType
A través de mapping, especifica claramente que "dog" corresponde al esquema Dog y "cat" corresponde al esquema Cat.

Las especificaciones OpenAPI completas son las siguientes:

openapi: 3.0.3
info:
  title: Pet Shop API
  version: 1.0.0

components:
  schemas:
    Dog:
      type: object
      properties:
        petType:
          type: string
          enum: [dog]
        name:
          type: string
        age:
          type: integer
        weight:
          type: number
        breed:
          type: string
        isVaccinated:
          type: boolean
        walkingSchedule:
          type: string
        favoriteToys:
          type: array
          items:
            type: string
        trainingLevel:
          type: string
      required:
        - petType
        - name
        - age

    Cat:
      type: object
      properties:
        petType:
          type: string
          enum: [cat]
        name:
          type: string
        age:
          type: integer
        weight:
          type: number
        isVaccinated:
          type: boolean
        isIndoor:
          type: boolean
        litterBoxType:
          type: string
        scratchingPostHeight:
          type: integer
        favoriteSleepingSpot:
          type: string
      required:
        - petType
        - name
        - age

    Pet:
      oneOf:
        - $ref: '#/components/schemas/Dog'
        - $ref: '#/components/schemas/Cat'
      discriminator:
        propertyName: petType
        mapping:
          dog: '#/components/schemas/Dog'
          cat: '#/components/schemas/Cat'

paths:
  /pets:
    get:
      summary: Get pet information
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'

Después de completar las especificaciones OpenAPI, utiliza la función de `importar` en Apidog. Apidog analizará todas las especificaciones, creará automáticamente los esquemas y endpoints correspondientes, y reconocerá correctamente la configuración de discriminator (se añade `enum` aquí para bloquear los valores de los parámetros).

importando OpenAPI para añadir discriminator y distinguir múltiples esquemas

Preguntas Frecuentes

1. ¿Cuándo usar Discriminator?

Debes usar un discriminator solo cuando tu endpoint ya incluye un campo que identifica los esquemas. En el ejemplo anterior, el campo petType existe en el diseño de la API y se utiliza para diferenciar entre tipos de mascotas.

El discriminator simplemente le dice a las herramientas cómo elegir el esquema correcto basándose en el valor de ese campo.

Si tu endpoint no incluye un campo de identificación de tipo, entonces un discriminator no es apropiado; usar oneOf por sí solo es suficiente.

Además, si tu esquema es simple o tiene solo unas pocas variaciones, es posible que no necesites un `discriminator` en absoluto.

2. ¿Debe usarse Discriminator con oneOf?

Sí. Un `discriminator` debe usarse junto con oneOf, anyOf o allOf. No puede definir esquemas por sí mismo, solo explica cómo distinguir entre múltiples esquemas posibles.

Conclusión

discriminator es una característica opcional en la especificación OpenAPI utilizada para mejorar la experiencia de usuario de oneOf/anyOf/allOf.

Cuando las especificaciones de tu endpoint ya contienen campos utilizados para identificar tipos, puedes configurar discriminator en Apidog para hacer la documentación de la API más clara e inteligente.

Por supuesto, si la configuración te resulta engorrosa o el esquema es relativamente simple, puedes usar completamente solo la composición de esquema como oneOf.