Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Muoversi lombardia: glossario #18

Open
ioggstream opened this issue Dec 18, 2018 · 3 comments
Open

Muoversi lombardia: glossario #18

ioggstream opened this issue Dec 18, 2018 · 3 comments

Comments

@ioggstream
Copy link
Contributor

@stefkohub.

Le info di glossario non le metterei direttamente qui ma in components.schemas.

Guarda in questo draft come le informazioni di glossario siano indicate sia sulla classe
che per campo.

https://github.com/teamdigitale/api-openapi-samples/blob/master/external-apis/spid-aa.yaml#L109

Un parser può semplicemente ricostruire tutto il gioco leggendo lo yaml e ricavare l'informazione completa e aggiornata.

eg.

    Point:
      externalDocs:
         url: URL VERSO IL GLOSSARIO
         x-glossary: true
      description: Un punto sulla mappa. Questo e' definito in un glossario e linkato tramite externalDocs
         oppure potremmo definire un x-glossary a questo livello.
      type: object
      properties:
        label:
          type: string
        type:
          type: string
        x:
          '$ref': '#/components/schemas/Longitudine'
        y:
          '$ref': '#/components/schemas/Latitudine'
      example:
        label: Rogoredo M3
        type: areadifermata
        x: 9.237421
        y: 45.433681

@stefkohub
Copy link

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
Copy link
Contributor Author

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
Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants