REST API-profil - Lint Processor (RAP-LP)

Beskrivning:

RAP-LP är ett kommandoradsverktyg för att linta OpenAPI v3-definitioner med hjälp av Spectral.
Verktyget är specifikt utvecklat för att linta OpenAPI-definitioner enligt den svenska REST API-profilens specifikation REST API-profil.

Innehållsförteckning

• REST API-profil - Lint Processor (RAP-LP)
  • Innehållsförteckning
  • Instruktioner för att komma igång snabbt
  • Versioner
  • Användning
  • Begränsningar
  • Support
  • FAQ
  • Bidra
  • Utveckling
  • Licens
  • Underhållare
  • Krediter och referenser

Instruktioner för att komma igång snabbt

Förutsätter att det finns en openapi.yaml att validera i den aktuella katalogen och beroende på hur man önskar att nyttja verktyget måste det finns installerade versioner av Node.js,npm, Podman eller Docker.

NPM

Notera: Att GitHub Packages (npm) kräver authentisering.
Konfigurera .npmrc mot 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.

Installera globalt med npm:

npm i -g @diggsweden/rest-api-profil-lint-processor@<version>
raplp -f openapi.yaml

Notera: Att en omstart av terminal kan behövas för att raplp ska kunna användas som kommando.

Installera lokalt som npm run script

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.

NPX

Kör utan installation och package.json:

npx @diggsweden/rest-api-profil-lint-processor@<version> -f openapi.yaml

Notera: Att npx laddar ned paketet till en tillfällig cache-mapp om det inte redan finns en version i node_modules/.bin

Podman

Kör med podman:

podman run --rm -v $(pwd):/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> -f /data/openapi.yaml

Docker

Kör med docker:

docker run --rm -v $(pwd):/data ghcr.io/diggsweden/rest-api-profil-lint-processor:<version> -f /data/openapi.yaml

Notera: 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

Alternativ att köra ifrån containern med podman/docker

1. 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>

2. 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.

Bygga från källkod

1. Klona ned projektet, gärna från senaste release tag.
2. Installera alla beroenden:

npm install
npm start -- -f openapi.yaml

Notera: Att alla kommandon lokalt körs med npm start --.

Versioner

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:

• Container Image
• NPM Package

Användning

Här beskrivs vilka användningsområden verktyget har med diverse flaggor som kan sättas för att nyttja verktygets funktionalitet.

Tillgängliga flaggor

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: UfnRules, SakRules, VerRules, FnsRules, ArqRules, DokRules, AmeRules, ForRules, DotRules, FelRules, MogRules.	string	–	Nej
-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

Notera: Att raplp i alla kommandon nedan ersätts med respektive miljös sätt att köra verktyget (npm, docker eller podman).

Validering med alla regler

För att validera en openapi-definition med verktyget, lägg till -f <YAML_FILE>

raplp -f openapi.yaml

Validering med utvalda regler

För att validera mot en specifik kategori av regler, lägg till -c <CategoryName>.

Notera: Att du kan lägga till flera regler som en kommaseparerad lista.

# Validera mot en specifik regel
raplp -f openapi.yaml -c DokRules

# Validera mot flera regler
raplp -f openapi.yaml -c DokRules,AmeRules,SakRules

Tillgängliga kategorier med regler

• AmeRules
• ArqRules
• DokRules
• DotRules
• FelRules
• FnsRules
• ForRules
• MogRules
• ResRules
• SakRules
• UfnRules
• VerRules

Validering som skriver felmeddelanden till en valfri loggfil

För att skriva felmeddelanden till en valfri loggfil, lägg till -l <FILE>

raplp -f openapi.yaml -l raplp.log

Notera: 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 -a

Validering som sparar loggdiagnostik i en fil

För att spara loggdiagnostik i en fil, lägg till -d <FILE>

raplp -f openapi.yaml -d logDiagnostic.log

Validering 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 --dex

Exempel med sökväg till avstämningsfil i Excel

raplp -f openapi.yaml --dex <PATH>

Visa information version

För att visa aktuell version av verktyget, lägg till --version

raplp --version

Visa hjälp

raplp --help

Riktlinjer och förklaringar

Vill du veta mer om de specifika reglerna som verktyget tillämpar, se avsnittet GUIDELINES för detaljer.

Förklaring av översikt för regelutfall

Om man väljer att köra verktyget i console 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.

Förklaring av detaljering för regelutfall:

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.

Exempel:

I exemplet ovan framgår det att kravet för regeln DOK.01 inte är godkänt och att det aktuella API:et inte uppfyller detta.
Kravet har bedömts ha allvarlighetsgraden Error eftersom API:et bryter mot ett SKALL/SKALL INTE-krav i REST API-profilen.
Det finns också information om var i den aktuella OpenAPI-specifikationen problemet återfinns.

Vidare framgår det att kravet för regeln DOK.03 inte är godkänt och att det aktuella API:et inte möter detta krav.
Kravet har bedömts ha allvarlighetsgraden Warning eftersom API:et bryter mot ett BÖR/BÖR INTE-krav i REST API-profilen.
Även här finns information om var i den aktuella OpenAPI-specifikationen problemet återfinns.

Begränsningar

• Det går endast att köra RAP-LP mot en enda YAML-fil åt gången.

Support

Om du har frågor, funderingar, buggrapporter etc, vänligen kontakta Digg - Agency for Digital Government

FAQ

Hur skapar jag ett GitHub Personal Access Token (PAT)?

1. Gå till GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token → Generate new token (classic).
2. Sätt en beskrivning för ditt token under Note och ett utgångsdatum under Expiration (ha utgångsdatum!).
3. Select scopes → read:packages
4. 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:packages

podman login ghcr.io
# username: ditt GitHub-användarnamn
# password: GitHub PAT med read:packages

Skrivåtkomst till mount från container

Vid 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.

1. Kolla rättigheter

   ls -ld /path/to/mount

2. Prova köra som root user

   podman 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

3. 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

4. Beroende på din miljö och vilka möjligheter du har, hantera åtkomstproblemet mer beständigt och återställ tidigare läs- och skrivrättigheter.

5. 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

Bidra

Om du vill bidra till projektet, vänligen följ instruktionerna i avsnittet Contributing.
För utvecklare finns det mer information i avsnittet Development.

Utveckling

• Vänligen kontakta Digg - Agency for Digital Government

Licens

European Union Public Licence v. 1.2 Se LICENS för mer detaljer.

Copyright: Contributor Covenant

Licens: CC-BY-4.0

Underhållare

Digg - Agency for Digital Government

Krediter och referenser

Speciellt tack till

• Arbetsförmedlingen – The Swedish Public Employment Service