RAP-LP är ett verktyg för att validera OpenAPI v3-specifikationer mot den svenska REST API-profilen med hjälp av Spectral.
Det är specifikt utvecklat för att validera OpenAPI-definitioner enligt den svenska REST API-profilens specifikation.
RAP-LP kan användas lokalt i CLI-läge eller API-läge, eller via webbgränssnittet.
Installationsguide
Introduktion
API-läge
Mer information
Följande instruktioner förutsätter att det finns en openapi.yaml att validera i den aktuella katalogen.
Beroende på hur man önskar att nyttja verktyget måste det finnas installerade versioner av Node.js,npm, Podman eller Docker.
Notera: Att GitHub Packages (npm) kräver authentisering.
Konfigurera.npmrcmot rätt registry och scope, antingen globalt eller lokalt för enskilda projekt -@diggsweden:registry=https://npm.pkg.github.com
Om du saknar inloggning med GitHub Personal access token (PAT), se FAQ.Notera: Att
<version>byts ut mot önskad version av verktyget, oftast senaste release tag. För mer information se versioner.
npm i -g @diggsweden/rest-api-profil-lint-processor@<version>
raplp -f openapi.yamlNotera: Att en omstart av terminal kan behövas för att
raplpska kunna användas som kommando.
Installera och lägg som devDependencies:
npm i --save-dev @diggsweden/rest-api-profil-lint-processor@<version>
Lägg till ett npm run script i din package.json med rätt sökväg till filen du vill validera:
{
"scripts": {
"lint-processor": "raplp -f openapi.yaml"
}
}Nu kan du använda npm run lint-processor.
Kör utan installation och package.json:
npx @diggsweden/rest-api-profil-lint-processor@<version> -f openapi.yamlNotera: Att npx laddar ned paketet till en tillfällig cache-mapp om det inte redan finns en version i node_modules/.bin
Kör med podman:
podman run --rm -v $(pwd):/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> -f /data/openapi.yamlKör med docker:
docker run --rm -v $(pwd):/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> -f /data/openapi.yamlNotera: Sökvägar kan hanteras olika beroende på miljö:
- Podman (Linux/macOS/WSL): -v $(pwd):/app/example
- Docker (PowerShell): -v "${PWD}:/app/example"
- Docker (CMD): -v %cd%:/app/example
-
Starta en podman/docker container:
podman run --rm -it --entrypoint /bin/sh -v $(pwd):/app/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version>
-
Kör din validering ifrån containern:
npm start -- -f /data/openapi.yaml
Notera: Att det kan uppstå problem vid körningar med podman och docker i kombination med flaggor som sparar information till filer. Användarens skrivrättigheter kan göra att filer inte dyker upp som önskat. Filerna kan finnas i containern men dyker inte i den mountade katalogen som specificerats. Se FAQ för mer information.
- Klona ned projektet, gärna från senaste release tag.
- Installera alla beroenden:
npm install
npm start -- -f openapi.yamlNotera: Att alla kommandon lokalt körs med
npm start --.
Verktyget går att köra lokalt i två olika lägen
CLI och API läge. Om inget läge sätts manuellt, är CLI alltid default.
Lägesövergripande kommandon
| Kommando | Beskrivning | Typ | Standard | Obligatorisk |
|---|---|---|---|---|
--help |
Visar tillgängliga kommandon, flaggor och användningsinformation för verktyget. | Boolean | false |
Nej |
--version |
Visar aktuell version av RAP-LP. | Boolean | false |
Nej |
-m, --mode |
Anger vilket körläge verktyget ska använda, om inget anges startas CLI-läge per automatik. | String | CLI |
Nej |
Oavsett vilket läge du kör går det att filtrera vilka regelkategorier du vill validera emot.
I dagsläget är följande regelkategorier från REST API-profilen tillgängliga:
| Regelkod | Regelkategori |
|---|---|
| DokRules | Dokumentation |
| DotRules | Datum- och tidsformat |
| ResRules | Resurser |
| UfnRules | URL Format och namngivning |
| MogRules | Mognad |
| SakRules | Säkerhet |
| AmeRules | API Message |
| ArqRules | API Request |
| FelRules | Felhantering |
| VerRules | Versionshantering |
| FnsRules | Filtrering, paginering och sökparametrar |
| ForRules | Förutsättningar |
Se information om hur du väljer regelkategorier vid validering under rubriken för antingen CLI eller API läge.
Strikt-läge aktiverar validering av OpenAPI-specifikationens struktur och semantik enligt OpenAPI 3 (OAS3).
När --strict används verifieras OpenAPI-specifikationen först enligt OAS3.
Kontrollen säkerställer att specifikationen är korrekt uppbyggd och semantiskt giltig innan validering mot REST API-profilens regler utförs.
Flaggan --strict fungerar både med CLI och API-läge.
I API-mode är strikt läge default, men kan stängas av.
Aktivera strikt-läge med:
raplp -f openapi.yaml --strictExempel på resultat när --strict används i kombination med CLI-läge:
Strict validation reported issues:
- Structural at components : should NOT have additional properties (line 6)
- Semantic at components.tags : Property "tags" is not expected to be here. (line 7)| Flagga | Beskrivning | Typ | Standard | Obligatorisk |
|---|---|---|---|---|
-f, --file |
Sökväg till OpenAPI-specifikation (YAML/JSON). | String | – | Ja |
-c, --categories |
Regelkategorier separerade med kommatecken. Tillgängliga: DokRules, DotRules, ResRules, UfnRules, MogRules, SakRules, AmeRules, ArqRules, FelRules, VerRules, FnsRules, ForRules. |
String | – | Nej |
RAP-LP erbjuder stöd för att logga fel, exportera diagnostiseringsinformation samt generera rapporter baserade på resultatet från en validering. Läs mer om de olika alternativen för CLI-läge nedan.
Flaggor för loggning
| Flagga | Beskrivning | Typ | Standard | Obligatorisk |
|---|---|---|---|---|
-l, --logError |
Sökväg till fil för felloggning från RAP-LP. Om inte angiven skrivs loggen till stdout. | string | stdout (om ej satt) | Nej |
-a, --append |
Append—utökar loggen i befintlig felloggningsfil (om --logError används). |
boolean | false |
Nej |
-d, --logDiagnostic |
Sökväg till fil för diagnostiseringsinformation från RAP-LP i JSON-format. | string | – | Nej |
--dex |
Sökväg till fil för diagnostiseringsinformation från RAP-LP i Excel-format. | string | – | Nej |
Validering som skriver felmeddelanden till en valfri loggfil
För att skriva felmeddelanden till en valfri loggfil, lägg till `-l `raplp -f openapi.yaml -l raplp.logNotera: Att varje körning skriver över den tidigare loggfilen.
För att lägga till loggning i samma fil, lägg till -a
raplp -f openapi.yaml -l raplp.log -aValidering som sparar loggdiagnostik i en fil
För att spara loggdiagnostik i en fil, lägg till `-d `raplp -f openapi.yaml -d logDiagnostic.logValidering som sparar information om regelutfall i en Excel-fil
För att spara information om regelutfall från diagnostiseringen till en avstämningsfil i Excel, lägg till --dex.
Om en specifik sökväg till avstämningsfilen ska anges, kan denna läggas till.
Om ingen sökväg anges, genererar verktyget automatiskt en ny avstämningsfil i den katalog där det körs.
Avstämningsfilen i Excel har ett fast format, om en egen version av filen ska användas måste den utpekade resursen hämtas med en kompatibel version av REST API-profilen.
Exempel utan sökväg till avstämningsfil i Excel
raplp -f openapi.yaml --dexExempel med sökväg till avstämningsfil i Excel
raplp -f openapi.yaml --dex <PATH>%%{init: {
"theme": "base",
"themeVariables": {
"primaryColor": "#fbf2f0",
"primaryTextColor": "#000",
"primaryBorderColor": "#cd7a6e",
"lineColor": "#666",
"secondaryColor": "#ffffff",
"tertiaryColor": "#ffffff"
}
}}%%
flowchart TD
A["OpenAPI-specifikation"]
A --> B["Ange fil med -f"]
B --> C{Välj regelkategorier?}
C -->|Nej| D["Alla regler används"]
C -->|Ja| E["Ange -c <br> DokRules, UfnRules..."]
D --> F{Använd strikt läge?}
E --> F
F -->|Nej| G["Validera"]
F -->|Ja| H["Validera med --strict"]
G --> I["Resultat visas i terminalen"]
H --> I
I --> J{Spara resultat?}
J -->|Nej| K["Klart"]
J -->|Fellogg| L["-l <fil>"]
J -->|Diagnostik JSON| M["-d <fil>"]
J -->|Excelrapport| N["--dex"]
L --> K
M --> K
N --> K
Verktyget kan även köras som en lokal HTTP-server, via API (Applikation Programming Interface). I detta läge kan funktionaliteten anropas via HTTP i stället för CLI-flaggor.
| Flagga | Beskrivning | Typ | Standard | Obligatorisk |
|---|---|---|---|---|
--enableUrlValidation |
Aktiverar URL-validering i API-läge. | boolean | false |
Nej |
--urlValidationConfigFile |
Konfigurationsfil för URL-validering (fallback: ./urlValidationConfig.cjs). |
string | ./urlValidationConfig.cjs |
Nej |
| Endpoint | Beskrivning |
|---|---|
/api/v1/docs |
Används för att hämta aktuell API-dokumentation med Swagger UI. |
/api/v1/api-info |
Används för att hämta information om API:et. |
/api/v1/validation/rules |
Används för att hämta lista med tillgängliga regelkategorier som stöds av verktyget. |
/api/v1/validation/validatespec |
Används för att validera en OpenAPI-specifikation mot REST API-profilens regler. |
/api/v1/validation/url |
Används för att validera en OpenAPI-specifikation från en angiven URL. |
/api/v1/validation/generate-report |
Används för att generera en rapport baserad på ett valideringsresultat. |
Vid körning i API-läge från en lokal server kan RAP-LP konfigureras med hjälp av miljövariabler.
| Miljövariabel | Beskrivning |
|---|---|
| RAP_LP_JSON_BODY_LIMIT | Maximalt tillåten storlek på JSON-requests. Defaultvärdet är 3mb |
| RAP_LP_MAX_CONCURRENT_REPORTS | Maximalt antal samtidiga rapportgenereringar som får bearbetas samtidigt. Defaultvärdet är 4 |
| RAP_LP_MAX_CONCURRENT_VALIDATIONS | Maximalt antal samtidiga valideringar som får bearbetas samtidigt. Defaultvärdet är 4 |
| RAP_LP_PERF_LOGGING | Anger om prestandaloggning ska användas, kan sättas till true eller false. Funktionen är inaktiverad som standard. |
| RAP_LP_LOG_TARGET | Anger var serverloggar ska skrivas, exempelvis stdout eller stderr. Defaultvärdet är stderr |
| RAP_LP_ALLOW_LOCALHOST_URL_VALIDATION | Anger om validering av specifikationer som lagras lokalt på localhost är tillåten. Inställningen används främst vid lokal utveckling och kan sättas till true eller false. Funktionen är inaktiverad som standard. |
| RAP_LP_PORT | Portkonfiguration för vilken port servern ska starta på och lyssna på inkommande requests. Defaultvärdet är 3000. |
Nedan följer exempel på hur API:ets endpoints kan anropas, inklusive nödvändiga headers, request bodies och exempel med curl.
Validera lokal OpenAPI-specifikation (/api/v1/validation/validatespec)
Request headers
Content-Type: application/json
Accept: application/jsonRequest body
{
"yaml": "<base64encoded file>",
"categories": ["DokRules", "UfnRules"],
"strict": true
}Exempel med curl
curl -X POST http://localhost:3000/api/v1/validation/validatespec \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d "{
\"spec\": \"$(base64 -w 0 openapi.yaml)\",
\"categories\": [\"DokRules\", \"UfnRules\"],
\"strict\": true
}"Validera OpenAPI-specifikation via URL (/api/v1/validation/url)
Kräver att API-läget startats med
--enableUrlValidation.
Request headers
Content-Type: application/json
Accept: application/jsonRequest body
{
"url": "<URL_TO_YAML_FILE>",
"categories": ["DokRules", "UfnRules"],
"strict": true
}Exempel med curl
curl -X POST http://localhost:3000/api/v1/validation/url \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"url": "<URL_TO_YAML_FILE>",
"categories": ["DokRules", "UfnRules"],
"strict": true
}'Generera Excel-rapport (/api/v1/validation/generate-report)
Request headers
Content-Type: application/json
Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheetRequest body
{
"report":[
{
"note":"Godkända regler - RAP-LP",
"rules":[
...
]
},
{
"note":"Ej godkända regler - RAP-LP",
"rules":[
...
]
},
{
"note":"Ej tillämpade regler - RAP-LP",
"rules":[
...
]
}
]
}Exempel med curl
curl -X POST http://localhost:3000/api/v1/validation/generate-report \
-H "Content-Type: application/json" \
-H "Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
-o avstamningsfil.xlsx \
--data-binary @report-payload.jsonHämta tillgängliga regelkategorier (/api/v1/validation/rules)
Exempel med curl
curl -X GET http://localhost:3000/api/v1/validation/rules \
-H "Accept: application/json"Hämta API-information (/api/v1/api-info)
Exempel med curl
curl -X GET http://localhost:3000/api/v1/api-info \
-H "Accept: application/json"%%{init: {
"theme": "base",
"themeVariables": {
"primaryColor": "#fbf2f0",
"primaryTextColor": "#000",
"primaryBorderColor": "#cd7a6e",
"lineColor": "#666",
"secondaryColor": "#ffffff",
"tertiaryColor": "#ffffff"
}
}}%%
flowchart TD
A[Starta RAP-LP i API-läge]
A --> B{Validera via URL?}
B -->|Nej| C["npm start -- -m api"]
B -->|Ja| D["npm start -- -m api --enableUrlValidation"]
C --> E["Server startad,<br> lyssnar på port"]
D --> E
E --> F{Vad vill du validera?}
F -->|Lokal OpenAPI-specifikation| G["POST<br>/api/v1/validation/validatespec"]
F -->|URL till OpenAPI-specifikation| H["POST<br>/api/v1/validation/url"]
G --> I["Skicka OpenAPI-specifikation"]
H --> I
I --> J["Valfritt:<br> Skicka med categories"]
J --> K["Valfritt:<br> Ange strict som <br>true eller false"]
K --> L["Ta emot valideringsresultat"]
L --> M{Vill du generera<br> Excel-rapport?}
M -->|Nej| N[Klart]
M -->|Ja| O["POST<br> /api/v1/validation/generate-report"]
O --> P["Skicka tidigare<br> valideringsresultat"]
P --> Q["Excel-fil med<br> regelutfall genereras"]
Q --> N
Main-branchen, feature-brancher, pre-release- och testversioner används med reservation för att de kan innehålla funktionalitet som inte är garanterad att den är testad på samma sätt som en stabil version.
Stabila versioner
Release ska alltid vara stabil och testad, vilket gör den till den föredragna versionen för att nyttja verktyget.
Dessa versioner är taggade med vX.X.X utan något suffix.
Pre-release- och testversioner
Pre-release-versioner är taggade med följande suffix:
- alpha → tidig testversion, ofta instabil
- beta → mer testad, men fortfarande pre-release
- rc → nära färdigställande, stabil release candidate
Rena testversioner är taggade med vX.X.X-dev följt av namnet på den branchen.
Dessa versioner är byggda för att testa funktionalitet som är under utveckling.
Alla versioner av verktyget hittar du här:
Vill du veta mer om de specifika reglerna som verktyget tillämpar, se avsnittet GUIDELINES för detaljer.
Det går endast att köra RAP-LP mot en enda OpenAPI-specifikation åt gången.
Om man väljer att köra verktyget i CLI-läge, så kommer diagnostiseringsinformationen på stdout.
I denna så kommer en sammanställning av det totala regelutfallet att visas.
- Verkställda och godkända regler:
- OK = Krav bedömt och hanterat för att möta kravet
- Verkställda och ej godkända regler
- EJ OK = Krav bedömt, men API:et möter inte kravet
- Ej tillämpade regler
- N/A = Krav bedömt men inte applicerbart på API:et
Exempel:
I exemplet ovan framgår det att kraven för reglerna AME.05 och VER.05 är godkända och att det aktuella API:et uppfyller dessa.
Däremot är kravet för regeln DOK.03 inte godkänt, vilket innebär att API:et inte möter detta krav.
Dessutom framgår det att reglerna SAK.10 och DOK.01 inte är tillämpade för det aktuella API:et.
Tillsammans med diagnostiseringsinformationen följer en detaljerad beskrivning av informationen för regelutfallet. I denna beskrivning framgår följande:
- Allvarlighetsgrad: Anger allvaret av problemet som upptäckts av regeln. De möjliga värdena är error och warning, vilka tolkas enligt följande:
- Error: Ett uppenbart fel som måste åtgärdas. I REST API-profilen motsvarar detta kravtypen SKALL och SKALL INTE.
- Warning: Ett möjligt fel som kan behöva åtgärdas. Vissa avvikelser från specifika regler kan dock tolereras. I REST API-profilen motsvarar detta kravtypen BÖR och BÖR INTE.
- Område: Det aktuella området i REST API-profilen som regeln gäller för.
- Sökväg: Sökvägen till felet, det vill säga den JSONPath som pekar på det fält som diagnostiken avser och som orsakade felet.
- Omfattning: Det omfång som denna diagnostik gäller.
- Länk till specifik designregel av kravet som verktyget tillämpar.
Exempel:
I exemplet ovan framgår det att kravet för regeln med id DOK.06 inte är godkänt och att den aktuella API-specifikationen inte uppfyller detta.
Kravet har bedömts ha allvarlighetsgraden Warning eftersom API-specifikationen bryter mot ett BÖR/BÖR INTE-krav i REST API-profilens område för regler som gäller dokumentation.
Genom sökvägen kan vi se var i den aktuella OpenAPI-specifikationen problemet återfinns.
Omfattningen visar på vilken rad i din API-specifikation felet börjar och slutar.
Längst ned ser du även en hänvisning till specifik dokumentation om den designregel som verktyget tillämpat.
- Gå till GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token → Generate new token (classic).
- Sätt en beskrivning för ditt token under
Noteoch ett utgångsdatum underExpiration(ha utgångsdatum!). - Select scopes → read:packages
- Skapa token → kopiera värdet direkt (visas bara en gång).
npm login --registry=https://npm.pkg.github.com
# username: ditt GitHub-användarnamn
# password: GitHub PAT med read:packagespodman login ghcr.io
# username: ditt GitHub-användarnamn
# password: GitHub PAT med read:packagesVid körningar med podman och docker i kombination med flaggor som sparar information till filer kan det uppstå problem kring skrivrättigheter som gör att filer inte dyker upp som önskat. Filerna kan finnas i containern men dyker inte i den mountade katalogen som specificerats.
Se till att containern har rättigheter att skriva till den katalog som du mountar.
-
Kolla rättigheter
ls -ld /path/to/mount
-
Prova köra som
root userpodman run -it -v $(pwd):/data --user root ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> -f /data/openapi.yaml -l /data/raplp.log --dex /data/avstamning.xlsx
-
För att testa om det är ett åtkomstproblem kan du temporärt prova om det går efter du gett alla skrivrättigheter till den mountade katalogen:
sudo chmod 777 /path/to/mount
-
Beroende på din miljö och vilka möjligheter du har, hantera åtkomstproblemet mer beständigt och återställ tidigare läs- och skrivrättigheter.
-
Du kan även prova:
sudo podman run -it -v $(pwd):/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> -f /data/openapi.yaml -l /data/raplp.log --dex /data/avstamning.xlsx
Om du har frågor, funderingar, buggrapporter etc. Vänligen kontakta Digg - Agency for Digital Government.
Om du vill bidra till projektet, vänligen följ instruktionerna i avsnittet Contributing.
För utvecklare finns det mer information i avsnittet Development.
Vänligen kontakta Digg - Agency for Digital Government
Programkod
European Union Public Licence v. 1.2
Dokumentation, övrigt
CC0 1.0
Digg - Agency for Digital Government
Speciellt tack till Arbetsförmedlingen – The Swedish Public Employment Service