Bruke OpenAPI

Utviklerportalen støtter bruk av OpenAPI / Swagger‑dokumentasjon.
Du kan legge til så mange Swagger‑dokumentasjonssider du trenger ved hjelp av metadata.json‑skjemaet.

Legge til OpenAPI‑definisjoner i metadata.json

Ved å bruke metadata.json‑skjemaet kan du legge til Swagger‑dokumentasjonssider ved å følge eksemplet under:

{
    "serviceName": "",
    "serviceDescription": "",
    "productName": "",
    "apiName": "",
    "productFolderDisplayName": "",
    "apiFolderDisplayName": "",
    "docsFolderDisplayName": "",
    "openApiFolderDisplayName": "",
    "utviklerportalBranches": ["", ""],
    "syncWithPortal":true,
    "openApis": [
        {
            "name": "Katalogen",
            "url": "https://catalog-p.plattform.nhn.no/swagger/v1/swagger.json",
            "servers": ["https://catalog-dev.plattform.nhn.no"]
        },
        {
            "name": "Utviklerportalen Interne API",
            "url": "https://utviklerportal.nhn.no/swagger/default/swagger.json"
        }
    ]
}

Schemaet for hvert openApi‑objekt ser slik ut:

"openApis": [
    {
        "name": string,
        "url": string,
        "servers": string[]
    },
    {
        "name": string,
        "url": string,
        "servers": string[]
    }
]

URL‑en som oppgis må peke til et gyldig og tilgjengelig swagger.json‑dokument for at Swagger‑UI‑skriptet skal kunne rendere korrekt.

Bruke Test Token Tool (TTT)

Utviklerportalens OpenAPI / Swagger‑implementering støtter bruk av Test Token Tool (TTT) for å generere token til «try‑it‑out»‑funksjoner.

For å aktivere og bruke TTT må du gå inn på OpenAPI‑innholds‑noden i Portal‑Backoffice. Der kan du oppgi et gyldig scope (én eller flere streng‑verdier) og audience (streng).

Når både scope og audience er oppgitt, vil TTT automatisk bli aktivert når Swagger‑dokumentet rendres.

Aktivere DPoP for Swagger‑dokumenter

Utviklerportalens OpenAPI / Swagger‑implementering støtter også DPoP.

Akkurat som med TTT kan DPoP slås på ved å åpne OpenAPI‑innholds‑noden i portalens backoffice.

Her finner du en enkel bryter som slår DPoP på eller av for den aktuelle innholds‑noden. Merk at for at DPoP skal fungere korrekt, må du inkludere alle nødvendige definisjoner i din swagger.json‑fil.

Hvis bryteren er satt og de nødvendige definisjonene er til stede, vil DPoP automatisk aktiveres for Swagger‑dokumentet ditt.

Angi sikkerhetsnivå

Du kan sette en numerisk verdi for security level på OpenAPI‑innholds‑noden i backoffice.

Dette sikkerhetsnivået brukes i forhold til Swagger/OpenAPI‑dokumenter som benytter HelseID / DPoP / Test Token Tool.

Hvor du setter det

Åpne OpenAPI‑innholds‑noden i backoffice og skriv inn en numerisk verdi i feltet Security level.

Du kan lese mer om sikkerhetsnivået i HelseID‑dokumentasjonen.

Angi HPR‑nummer, personidentifier og personnnavn

Du kan også oppgi valgfrie user‑claim‑verdier på OpenAPI‑innholds‑noden i backoffice:

• HPR‑nummer (hprNumber)
• Personidentifier (personIdentifier, mappes til pid)
• Personnavn (personName, mappes til name)

Disse verdiene brukes av Test Token Tool‑flyten for Swagger/OpenAPI‑dokumenter som bruker HelseID.

Hvor du setter dem

Åpne OpenAPI‑innholds‑noden i backoffice og fyll inn de aktuelle feltene.

Når de er satt, blir verdiene sendt videre som bruker‑claims i token‑forespørsler:

• userClaimsParameters.hprNumber
• userClaimsParameters.pid
• userClaimsParameters.name