Komplettere OpenAPI dokumentasjon

[prange]

Introduction

OpenAPI spesifikasjonen er ikke fullstendig og vi anmoder om at det innføres rutiner som i større grad sørger for at kode og spec er i synk og tilgengelig fortløpende.

Description

OpenAPI spesifikasjonen og Swaggerdokumentene er uvurderlige kilder til informasjon om integrasjon mot Dialogporten. Spesielt nå som API'et fortsatt endres relativt hyppig er det veldig nyttig for oss som tester ut Dialogporten å ha god og nøyaktig OpenAPI-spesifikasjon slik at vi enkelt kan henge med og evt autogenerere klient-kode.
F.eks. er returtypen til GET /api/v1/serviceowner/dialogs/{dialogId}/transmissions bare en string i spesifikasjonen.

I tillegg er typespesifikasjonene unike for hvert endepunkt slik at samme datastruktur er navngitt ulikt for for f.eks. GET /dialogs og GET /dialogs/{dialogId}.

En alternativ løsning er her jo å publisere datatypene som en NuGet pakke fortløpende (#1137).

Jeg vil tro å få på plass dette kan spare dere for en del spørsmål om APIet framover.

[oskogstad]

Vi har en form for automatisk sjekk for dette (snapshot test av OpenAPI-dokumentet), men ingen sjekk for å dekke akkurat denne feilen du fant med transmissions ... skal se på det. 🤔
Vet og vi har en del feil/mangler rundt hvilke statuskoder som kan komme fra hvert endepunkt.

GET /dialogs og GET /dialogs/{dialogId} har ikke samme datastruktur, forsto ikke helt hva du mente her?
(Search-endepunktet (GET /dialogs) har en hel del properties fjernet, f.eks. alt av attachments, transmissions, gui-actions)

#1137 skal vi muligens se på i neste sprint som starter straks 😊

Har fiksa transmissions sin returtype, skal få pusha asap 🚀
Takk for feedback! 💪🏼

[prange]

Ref datatyper: Det er enkelte datatyper som er strukturelt identiske, men har ulike navn avhengig av endepunkt og plassering, f.eks ***ActorDto, ***AttachmentDto eller ***ActivityDto (ta høyde for at jeg ha blingsa og ikke sett de strukturelle forskjellene)