Reglas de generación de datos

Esta función sólo está disponible en API Connect Enterprise as a Service

Las reglas de generación de datos guían al verificador automático en la elección de valores para llenar los parámetros y las cargas útiles de sus solicitudes.

Existen reglas predeterminadas derivadas de la definición de API y las extensiones, pero a veces desea alterarlas temporalmente, ya sea para mejorar la precisión general del verificador automático o para adaptar sus solicitudes a un caso de uso específico, y lo hace añadiendo reglas personalizadas a la sección Tipos de datos de la configuración del perfil.

Una regla de generación de datos enlaza un generador de datos a un esquema o tipo en la definición de API de forma que, cuando el verificador automático ensambla los datos para una solicitud y encuentra ese esquema o tipo, utiliza el generador para proporcionar un valor adecuado en ese punto.

Generadores de datos

Un generador de datos describe una secuencia interminable de valores, y siempre que el verificador automático llama a un generador, toma el siguiente valor de la secuencia.

La sintaxis de las reglas de generación reutiliza términos del esquema JSON donde las restricciones implícitas en un esquema son suficientes para guiar al verificador automático en la generación de valores conformes. Estas restricciones que se producen en la definición de API ayudan a informar a las reglas predeterminadas.

Constante

El generador de constantes siempre devuelve el mismo valor, que puede ser de cualquier tipo simple.

const: 0

# ==> 0, 0, 0, ...

const: Thursday

# ==> "Thursday", "Thursday", "Thursday", ...

Enumeración

El generador de enumeración devuelve valores seleccionados aleatoriamente de una lista determinada, que puede ser de cualquier tipo simple.

enum:
  - 0
  - 1
  - 2

# ==> 1, 0, 2, 0, ...

enum:
  - Thursday
  - Friday
  - Saturday

# ==> "Friday", "Saturday", "Saturday", ...

Patrón

El generador pattern devuelve valores de serie que coinciden con una expresión regular determinada.

pattern: '[0-9]{3}'

# ==> "884", "924", "121", ...

pattern: '[a-z][a-z_]{0,15}'

# ==> "dbe", "kg_cfsv", "dhbfgbjxavmsaxq", ...

Rango

El generador de rango devuelve valores numéricos distribuidos uniformemente sobre un rango determinado (inclusive).

minimum: 0
maximum: 10

# ==> 10, 6, 8, ...

Si se omite cualquiera de los puntos finales, el valor predeterminado es el más negativo o el más positivo del tipo:

minimum: 0

# ==> 10029625, 3162517758, 841054690, ...

Semántica

El generador semántico devuelve valores que se ajustan a alguna categoría semántica predefinida, que cubre nombres, direcciones, números de tarjeta de crédito, etc. El conjunto de categorías es el mismo que el permitido en las extensiones de API.

semantic: email

# ==> "herbertschaden@fahey.net", "emmyfarrell@cruickshank.com", "vilmaprohaska@zboncak.org", ...

semantic: first_name

# ==> "Antwan", "Connie", "Modesto", ...

Recurso

El generador de recursos devuelve valores que son identificadores exclusivos de instancias de recursos de un tipo determinado, seleccionados de forma aleatoria de la agrupación de instancias existentes. El identificador de una instancia se toma de la propiedad id_name del tipo de recurso definido en las extensiones de API y su tipo y formato variarán en consecuencia.

resource: Customer

# ==> "e5537298-9041-47fc-b97e-c910d8f9d971", "f60521c8-2ccb-4036-a742-9f350271675f", "e5537298-9041-47fc-b97e-c910d8f9d971", ...

Matriz

El generador de matriz devuelve valores de matriz cuyo contenido se llena a partir de un generador de datos definido de forma recursiva. La longitud de la matriz se elige de forma aleatoria entre minItems y maxItems inclusive.

items:
  pattern: '[0-9]{3}'
minItems: 3
maxItems: 3

# ==> ["770", "496", "219"], ["431", "895", "331"], ["864", "130", "204"], ...

items:
  enum:
    - 0
    - 1
minItems: 0
maxItems: 5

# ==> [], [1, 0, 1, 1], [0], ...

Objecto

El generador de objetos devuelve valores de objeto cuyas propiedades se rellenan a partir de generadores de datos con nombre, definidos de forma recursiva.

properties:
  x:
    minimum: 0
    maximum: 100
  y:
    minimum: 0
    maximum: 100

# ==> {"x": 59, "y": 63}, {"x": 22, "y": 8}, {"x": 95, "y": 57}, ...

properties:
  code:
    pattern: '[0-9]{3}'
  language:
    enum:
      - en
      - fr
      - de

# ==> {"code": "452", "language": "fr"}, {"code": "504", "language": "en"}, {"code": "846", "language": "fr"}, ...

Si el esquema de destino no necesita una propiedad, se puede marcar con un atributo optional que especifica una frecuencia (entre 0.0 y 1.0) que determina la frecuencia con la que se incluye la propiedad en el objeto generado (donde 0 significa nunca y 1 significa siempre).

properties:
  code:
    pattern: '[0-9]{3}'
  language:
    optional: 0.5
    enum:
      - en
      - fr
      - de
  tag:
    optional: 0.0

# ==> {"code": "452", "language": "fr"}, {"code": "504", "language": "en"}, {"code": "846"}, ...

Opción

El generador de opciones devuelve valores seleccionados aleatoriamente de una lista determinada de generadores de datos, utilizando ponderaciones opcionales para sesgar el resultado. Las alternativas deben ser generadores simples, lo que excluye los generadores array y object .

choice:
  # bias the selection towards English
  - const: en
    weight: 5
  - const: fr
  - const: de

# ==> "en", "en", "en", ..., "de", "en", ...

choice:
  # normal values in the range 1-10
  - minimum: 1
    maximum: 10
    weight: 98
  # with a small percentage of outliers
  - const: 999
    weight: 2

# ==> 6, 3, 9, 1, ..., 999, 6, ...

Reglas de generación de datos

Una regla de generación de datos enlaza un generador de datos con un esquema que se produce en la definición de API para que el verificador automático sepa cómo generar valores para ese esquema en una llamada de API. Las reglas se especifican en la sección Tipos de datos de la configuración del perfil y alteran temporalmente las reglas predeterminadas derivadas de la definición y las extensiones de la API.

Los esquemas se producen ampliamente en la especificación OpenAPI , pero hay tres ubicaciones clave que tienen más relevancia para el verificador automático donde el perfil permite reglas de sustitución:

  • Esquemas con nombre
  • Parámetros
  • Cuerpos de solicitud en línea

Esquemas con nombre

Una regla de esquema asigna un generador de datos a un esquema con nombre de la definición de API, que se encuentra en definitions (OpenAPI 2.0) o components/schema (OpenAPI 3.0). El verificador automático utilizará el generador especificado siempre que se produzca el esquema con nombre en una solicitud.

Las reglas de esquema aparecen en la sección schemas de la configuración de perfil, en Datatypes.

Puesto que se trata de una alteración temporal, el generador puede estar incompleto para el esquema original, y el verificador automático volverá a utilizar las reglas predeterminadas para cubrir los huecos. En concreto, si el esquema describe un tipo de objeto, el generador sólo necesita nombrar un subconjunto de las propiedades del objeto, y el verificador automático aplicará la alteración temporal para esas propiedades, pero utilizará las reglas predeterminadas para el resto.

Por ejemplo, dado este esquema con nombre en la definición de API:

Movie:
  type: object
  properties:
    title:
      type: string
    release_date:
      type: string
      format: date
    language:
      description: Two-letter ISO 639-1 language code
      type: string
      pattern: '[a-z]{2}'

La regla predeterminada derivada del esquema devuelve valores como:

{
  "title": "mkLHM22Ohabb6YG4-wdZFUwxQa7dn",
  "release_date": "2018-09-14",
  "language": "jq"
}

Puede refinar esto alterando temporalmente las reglas predeterminadas para las propiedades title y language :

Datatypes:
  schemas:
    Movie:
      properties:
        title:
          semantic: sentence
        language:
          enum:
            - en
            - fr
            - de

Esta regla enlaza un generador de objetos (introducido por la palabra clave properties) con el esquema denominado Movie que, combinado con la regla predeterminada para release_date , devuelve valores como:

{
  "title": "What dog everybody am myself hourly meeting how group over example her",
  "release_date": "2094-06-31",
  "language": "de"
}

Parámetros

Una regla de parámetro enlaza un generador de datos con un parámetro con nombre dentro de una operación que se encuentra bajo paths en la definición de API.

Las reglas de parámetro aparecen en la sección operations de la configuración del perfil, en Datatypes.

Por ejemplo, dada esta definición de parámetro en GET /movies en la definición de API que restringe el número de películas devueltas en una sola llamada:

paths:
  /movies:
    get:
      parameters:
        - name: limit
          in: query
          description: Sets an upper bound on the number of movies returned
          schema:
            type: integer

La regla predeterminada derivada de esta definición devolverá valores del rango entero completo, pero puede sustituirla con una regla en la configuración de perfil que especifique un rango más realista, con valores atípicos ocasionales para comprobar la lógica de validación:

Datatypes:
  operations:
    /movies:
      get:
        parameters:
          - name: limit
            data:
              choice:
                - minimum: 1
                  maximum: 500
                  weight: 95
                - const: 0
                  weight: 3
                - const: 8000000
                  weight: 2

El formato de la regla sigue el formato de la definición original pero con la palabra clave data en lugar de schema para introducir el generador de datos.

En OpenAPI, un parámetro se identifica unívocamente por un nombre y una ubicación (por lo que el mismo nombre podría utilizarse, por ejemplo, tanto en la consulta como en la cabecera), por lo que las reglas de los parámetros permiten la propiedad in como opcional cuando sea necesario para desambiguar. No se utiliza en este ejemplo porque el parámetro de consulta es el único denominado limit.

El verificador automático sólo admite parámetros de tipo query y path en la actualidad (y body en OpenAPI 2.0). Las reglas enlazadas a otros tipos de parámetros se ignoran.

Cuerpo de la solicitud

Una regla de cuerpo de solicitud enlaza un generador de datos con el cuerpo de una solicitud donde el esquema correspondiente se especifica directamente como parte de la operación en la definición de API, en lugar de a través de una referencia a un esquema con nombre.

Las reglas de cuerpo de solicitud aparecen en la sección operations de la configuración del perfil, en Datatypes.

Por ejemplo, dada esta definición de la carga útil para una solicitud POST :

paths:
  /movies:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/Movie'
                - properties:
                    keywords:
                      type: array
                      items:
                        type: string

La siguiente regla genera algunas palabras clave apropiadas para adjuntar a una nueva película (donde la película en sí está cubierta por las reglas discutidas anteriormente):

Datatypes:
  operations:
    /movies:
      post:
        requestBody:
          content:
            application/json:
              data:
                properties:
                  keywords:
                    # pick up to 3 items from the following list
                    items:
                      enum:
                        - avant-garde
                        - dystopia
                        - epic
                        - postmodern
                        - remake
                        - shootout
                    minItems: 0
                    maxItems: 3

Al igual que con las reglas de parámetro, el formato sigue el de la definición original pero con data en lugar de schema. La definición está en el estilo de OpenAPI 3.0, pero la regla puede funcionar para OpenAPI 2.0 , así como siempre que el tipo de contenido sea coherente; de forma alternativa, a partir de una definición de OpenAPI 2.0 , puede utilizar una regla de parámetro body para especificar la carga útil, pero eso no funciona para 3.0.