"Try-it-out" funksjonalitet

Dette dokumentet beskriver noen betraktninger for «Try it out»‑funksjonaliteten.

Hva er det?

Som en del av metadata.json‑filen finnes det en seksjon hvor du kan definere en lenke til et Swagger‑endpoint. Dataene blir importert inn i Utviklerportalen, og data‑elementer opprettes i Umbraco. Nedenfor er et eksempel på en metadata.json‑fil.

{
  "serviceName": "Plattform",
  "productName": "Utviklerportal",
  "apiName": "API Management Platform",
  "openApis": [
    {
        "name": "Katalogen",
        "url": "https://catalog-p.plattform.nhn.no/swagger/v1/swagger.json",
        "servers": ["https://catalog-p.plattform.nhn.no"]
    },
    {
      "name": "Utviklerportalen Interne API",
      "url": "https://app-utviklerportal-utvikling.azurewebsites.net/swagger/v1/swagger.json"
    }
]
}

Swagger‑grensesnittet vil bli renderet som en integrert del av Utviklerportalen, og brukeren kan utforske Swagger‑ (OpenAPI‑) grensesnittet uten å forlate portalen. Som en del av Swagger‑grensesnittet finnes det en «Try it out»‑seksjon, og det er noen få innstillinger som må konfigureres for at dette skal fungere.

«server»-attributtet i metadata.json‑filen

Først må servers‑attributtet settes i openApis‑seksjonen. Hvis dette ikke settes, vil kallene i «Try it out» bli gjort fra URI‑en til Utviklerportalen (vanligvis https://utviklerportal.nhn.no). Siden ditt Swagger‑endpoint ikke ligger der, vil det tydeligvis ikke fungere. Når servers‑attributtet er definert, fylles en nedtrekksmeny på Swagger‑siden med tilgjengelige servere, og brukeren kan velge riktig server. Dette kan typisk være én server for test‑miljø og én for produksjons‑miljø. Ofte finnes det bare én server (test‑miljø), og den vil da bli valgt som standard i nedtrekksmenyen.

Appen må hviteliste Utviklerportalen

Når en bruker trykker «Try it out», sendes det en JavaScript‑forespørsel til serveren. På grunn av CORS‑policyen må serveren som mottar forespørselen tillate kall fra et annet domene. Følgende CORS‑header‑egenskaper må derfor settes på den tjenesten som kalles:

• Access-Control-Allow-Origin
  Angir hvilken opprinnelse (domene) som får lov til å aksessere ressursen. Du kan spesifisere et bestemt domene eller bruke * for å tillate alle domener.

• Access-Control-Allow-Methods
  Angir hvilke HTTP‑metoder (GET, POST, PUT, DELETE osv.) som er tillatt.

• Access-Control-Allow-Headers
  Angir hvilke overskrifter klienten kan bruke i forespørselen.

• Access-Control-Allow-Credentials
  Angir om responsen kan eksponeres når credentials‑flagget er satt til true. Må være en boolsk verdi.

Vanligvis bør du sette

Access-Control-Allow-Origin: https://utviklerportal.nhn.no

Under er et eksempel på hvordan CORS‑header‑ene kan settes i applikasjonen som blir kalt. Verdien for host hentes typisk fra appsettings.json eller en miljøvariabel.

```csharp
logger ??= LoggerFactory.Create(conf => { }).CreateLogger("CorsExtension");

var hosts = config.GetSection("AllowedHosts").Get<string[]>();
if (hosts is { Length: > 0 })
{
    logger.LogInformation("Using these allowed hosts: {hosts}", String.Join(",", hosts));
    services.AddCors(options =>
    {
        options.AddDefaultPolicy(builder =>
            builder.WithOrigins(hosts)
                .AllowAnyHeader()
                .AllowCredentials()
                .AllowAnyMethod());
    });
}

Automatisk CORS‑verifisering

Utviklerportalen verifiserer automatisk CORS‑konfigurasjonen for hver konfigurerte API‑server når en Swagger‑UI‑side lastes.
Hvis CORS‑innstillingen ikke er aktivert på den aktuelle API‑en, vil «TRY ME»‑funksjonaliteten i Swagger‑UI ikke fungere.

Når du åpner en side i Utviklerportalen der Swagger‑API‑en er feilkonfigurert, vil Utviklerportalen vise en advarsel samt instruksjoner om hvordan du retter opp problemet.

Hva som blir sjekket i verifiseringsprosessen

Tre CORS‑respons‑headere blir verifisert:

Alle tre må bestå for at CORS‑sjekken skal lykkes.

Bannertyper

Det finnes tre mulige utfall for hver server‑URL:

• Ingen banner (suksess): Alle CORS‑headere er korrekt konfigurert. Ingenting vises til brukeren.
• Gult advarselsbanner: Serveren svarte, men én eller flere CORS‑headere mangler eller er feil. Banneren lister nøyaktig hvilke headere som mangler, og viser opprinnelsen som API‑eieren må hviteliste (f.eks. https://utviklerportal.nhn.no).
• Rødt feilmeldingbanner: CORS‑sjekken kunne ikke fullføres. Dette kan skje hvis:
  • Serveren ikke kunne nås
  • Forespørselen timeoutet (5‑sekundersgrense)
  • URL‑en peker til en privat eller intern adresse

Løse CORS‑problemer

Hvis et gult advarselsbanner vises, må API‑eieren oppdatere serverens CORS‑konfigurasjon slik at de manglende headerne inkluderes.
Se dokumentasjonen for ditt programmeringsspråk/rammeverk for veiledning og kodeeksempler.

Hvis et rødt feilmeldingbanner vises, kontroller at:

• URL‑en som er konfigurert i servers‑egenskapen er korrekt og publikt tilgjengelig
• Serveren er i drift og svarer på forespørsler
• URL‑en peker ikke til en privat eller intern nettverksadresse (f.eks. localhost, 127.0.0.1, 10.x.x.x, 192.168.x.x)

Generere token via HelseID test‑token‑verktøy (TTT) – definere scope og audience

Utviklerportalen støtter forespørsels‑interseptjon for «try‑it‑out»‑funksjonaliteten i Swagger‑UI.

Bruken av denne funksjonen er valgfri og kreves kun når forespørsler skal autentiseres med HelseID‑test.

Funksjonen vil avskjære forespørselen som Swagger‑UI lager, generere token via TTT og endre forespørsels‑headeren tilsvarende.

Et endpoint og en autentiserings‑nøkkel for TTT er allerede definert for Utviklerportalen og trenger ikke oppgis, men enkelte variabler må settes i ditt OpenAPI‑dokument før forespørselen kan avskjæres og token kan genereres.

For at forespørsels‑interseptor‑funksjonen skal kjøre og generere et token via TTT, må du definere korrekt scope og audience i backoffice for OpenAPI‑siden din.

Disse feltene vil senere kunne redigeres i metadata.json, men foreløpig må du gjøre dette manuelt i backoffice.
De nødvendige feltene for å trigge interseptjon er:

• Audience – streng
• Scope – liste av strenger (string[])

Du kan også skjule «Authorize»‑knappen i backoffice ved å bruke bryteren på OpenAPI‑siden.

Hvis både audience og scope er oppgitt, vil forespørselen som Swagger‑UI lager i «try‑it‑out»‑funksjonen bli avskjært, og forespørsels‑headeren vil bli endret til å inkludere tokenet som TTT har generert.

Forespørselen som Swagger‑UI lager i «try‑it‑out»‑funksjonen vil kun bli avskjært for å generere et token via TTT dersom audience og scope er definert. Eventuelle forespørsler uten scope og audience vil ikke bli avskjært eller modifisert.