Hvad er Swagger?
Swagger er en samling af værktøjer, som gør det nemmere at udvikle, interagere og dokumentere arbejde med API'er (kommunikation mellem to programmer).
I dette eksempel bruges Swagger til at vise, hvad der vil være muligt at gøre gennem den nye funktionalitet 'REST API' for Plandata indberetning.
Fordelen med Swagger er, at man kan opsætte en brugergrænseflade, som er nem at dele og kan tilgås gennem et link.
Swagger kræver også kun én opsætning af udviklerholdet, i stedet for f.eks. at alle brugere af REST API'en selv skal opsætte kommunikationen, downloade filer og andet gennem lignende værktøjer som f.eks. Postman.
Swagger er desværre ikke ment som det mest brugervenlige værktøj, da det samtidig skal fungere som dokumentation til udviklingsprocessen. Denne guide er forhåbentlig med til at hjælpe førstegangsbrugere godt i gang.
Links til Swagger for TEST og PREPROD miljøerne
Link til Swagger kan findes i dette afsnit. Dog kan Swagger ikke bruges til meget før man har opsat en authorize token, som giver adgang til at bruge Swaggers forskellige kald på det relevante miljø (se næste afsnit):
PREPROD: https://indberetpreprod.plandata.dk/plandata-api/swagger/
Opsæt "Authorize" token
Før man kan bruge Swagger, så skal man hente og bruge en gyldig "token" for det miljø, som man vil arbejde med.
OBS: Du vil have de samme rettigheder tilsvarende den bruger du vælger. Hvis din PREPROD bruger f.eks. ikke må oprette planer, så kan du heller ikke gøre dette igennem Swagger.
TEST-miljøet
I TEST miljøet hentes token via TIP, hvor der findes et stort antal oprettede TIP-brugere med forskellige privilegier.
For at hente en access token, gøres følgende:
1. Tilgå OpenID Connect (OIDC) siden https://indberettest.plandata.dk/plandata-api/oidcClient/index
2. I toppen, klik "Login/forny session":
3. Brugeren bliver viderestillet til TIP.
4. Fremsøg relevant bruger, som man gerne vil bruge, og klik "Log på"
5. Brugeren bliver herefter viderestillet tilbage til OIDC siden
Hvis alt er gået godt så skal teksten efter Status: være "Bruger er logget ind". I toppen vises også JSON data for brugerens profil, inklusive brugerens navn og en liste af privilegier (hvis brugeren har nogle tildelt):
Herefter kan du finde din token ved "Access token" på siden - ej at forveksle med "ID token". Denne token skal kopieres:
PREPROD-miljøet
For at hente en access token, gør følgende:
1. Tilgå OpenID Connect (OIDC) siden for PREPROD på https://indberetpreprod.plandata.dk/plandata-api/oidcClient/index
2. I toppen, klik "Login/forny session":
3. Brugeren bliver viderestillet til NemLog-in.
4. I toppen, vælg "Test login":
5. Udfyld med din testbruger
6. Her kan du blive spurgt om at logge ind som enten "private user" eller "professional user". Vælg i dette tilfælde "professional user".
7. Brugeren bliver herefter viderestillet tilbage til OIDC-siden.
Hvis alt er gået godt så skal teksten efter Status: være "Bruger er logget ind". I toppen vises også JSON data for brugerens profil, inklusive brugerens navn og en liste af privilegier (hvis brugeren har nogle tildelt):
Herefter kan du finde din token ved "Access token" på siden - ej at forveksle med "ID token". Denne token skal kopieres:
Indsæt token i Swagger
Når en gyldig token er blevet indhentet, kan denne indsættes i Swagger. I øverste højre hjørne af Swagger siden er der en "Authorize" knap:
Klik på denne for at indsætte den gyldige token. I tekstfeltet skrives der "Bearer" (vigtigt at det starter med stort B), mellemrum, og din token:
Klik "Authorize", og derefter kan boksen lukkes med "Close". Swagger medsender nu token med til kald til API'en.
Generel introduktion til brug af Swagger
Overordnet kan Swagger deles op i to ting: "Parameters" og "Responses".
Parameters er der, hvor man skriver "input"-værdier til kaldet, som man sender afsted. Det vil sige de værdier, som man skal bruge til at oprette, opdatere, hente planer osv.
Dette kan f.eks. være planID'et, status på planen, osv.
Responses er, hvor systemet sender et svar tilbage ift. det afsendte kald. Dette kan være et svar vedrørende, at alt gik godt, men også at der er fejl, eller at indtastede værdier er forkerte, osv.
Nedenstående screenshots gennemgår de grundlæggende funktionaliteter i Swagger. Efterfølgende er forklaringerne til hvert nummer.
Parameters afsnittet:
1. "Try it out" knappen bruges til at aktivere redigering i Swagger. Hvis denne ikke er brugt, så er det ikke muligt at redigere parametre til kaldet.
2. Felter som har "required" skal udfyldes, før man kan bruge kaldet. Ellers får man en fejlbesked om manglende værdier.
3. Denne type af parameter kræver, at brugeren selv indtaster værdien.
4. Denne type af parameter er en dropdown, hvor det kun er muligt at vælge valide værdier.
5. "Execute" knappen bruges til at sende kaldet afsted.
a. Herefter får man et response/svar tilbage fra systemet, som dukker op lige under "Parameters". Indtil man sender et kald afsted, vil der kun være forklaringstekst og eksempler for responses under "Parameters".
6. Denne type af parameter er en JSON-streng, som brugeren selv skal redigere manuelt.
OBS Eksemplet til kaldet har alle kaldets mulige værdier, så brugeren må selv fjerne og redigere ift. hvilke værdier, som de vil sende med. Ikke alle værdier er relevante for alle planstatusser. F.eks. har kladde til forslag ikke en ikrafttrædelsesdato.
Hvis en værdi fjernes fra kaldet og derved ikke sendes afsted (f.eks. fjerner man "plannavn" fra kaldet), så vil planens plannavn bevare sin originale værdi, og den ændres ikke. Det er desværre ikke muligt at nulstille eksemplet uden at genindlæse siden, hvis man f.eks. skriver forkert eller vil have det originale eksempel tilbage. Det kan anbefales at kopiere eksemplet ind i f.eks. Notepad, hvis man regner med at arbejde en del med det Husk at hvis man genindlæser siden, så skal man indsætte authorize token igen.
Responses afsnittet:
7. Alle svar indeholder en kode, som overordnet forklarer, hvordan kaldet til systemet gik. F.eks. er 200 og 204 koder ift. success, mens f.eks. 400 eller 404 koder er ift. problemer med kaldet
8. Uddybende forklaring på, hvad svarets kode betyder.
9. Nogle svar fremsender også information om den plan, som man har arbejdet med. Dette er et eksempel på, hvilken data man kan få med i svaret.
OBS: Før man sender et kald afsted, så vil responses afsnittet kun indeholde response eksempler.