Muoversi lombardia: glossario about api-openapi-samples

[stefkohub]

Sono d'accordo sul posizionare le info di glossario in components.schemas.

A tal proposito ti propongo una struttura come questa:

components:
  schemas:
    taxCode:
      $ref: '#/components/x-glossary/teamdigitale/TaxCode'
    Problem:
      $ref: '#/components/x-glossary/teamdigitale/Problem'

  x-glossary:
    teamdigitale:
      TaxCode:
        $ref: "https://raw.githubusercontent.com/teamdigitale/openapi/master/docs/schemas/tax_code.yaml#/TaxCode"
      Problem:
        $ref: "https://raw.githubusercontent.com/teamdigitale/openapi/0.0.1/docs/schemas/problem.yaml#/Problem"
      description: "Glossario definito dal Team Digitale"
      publisher: Team Digitale
      ecosystem: Eventuale Ecosistema
      version: Versione

In questo modo abbiamo:

1. la possibilità di definire modelli a partire da un glossario esterno definito
2. la possibilità di definire più di un glossario a cui fare riferimento negli schema
3. la possibilità di descrivere in termini business, con i campi opzionali description, publisher, ecosystem e version lo specifico glossario

[ioggstream]

Ciao @stefkohub

• capito l'obiettivo
• potremmo farlo nel file sorgente (eg. schemas/glossario-muoversi.yaml#/x-glossary/Tax-Code)
• non cambierei l'alberatura di OAS invece. Il glossario, come la definizione gdpr lo ricaverei dai datatype, non dall'API.

[stefkohub]

Concordo, la struttura x-glossary può andare in un YAML separato, e contenere sia le informazioni dei datatype che le informazioni "di business" accessorie.