You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
RAP-LP är ett kommandoradsverktyg för att linta OpenAPI v3-definitioner med hjälp av [Spectral](https://github.com/stoplightio/spectral). Verktyget är specifikt utvecklat för att linta OpenAPI-definitioner enligt den svenska REST API-profilens specifikation [REST API-profil](https://dev.dataportal.se/rest-api-profil).
20
+
RAP-LP är ett kommandoradsverktyg för att linta OpenAPI v3-definitioner med hjälp av [Spectral](https://github.com/stoplightio/spectral).<br>
21
+
Verktyget är specifikt utvecklat för att linta OpenAPI-definitioner enligt den svenska REST API-profilens specifikation [REST API-profil](https://dev.dataportal.se/rest-api-profil).
-[Instruktioner för att komma igång snabbt](#instruktioner-för-att-komma-igång-snabbt)
28
28
-[Versioner](#versioner)
29
29
-[Användning](#användning)
30
30
-[Begränsningar](#begränsningar)
31
31
-[Support](#support)
32
+
-[FAQ](#faq)
32
33
-[Bidra](#bidra)
33
34
-[Utveckling](#utveckling)
34
35
-[Licens](#licens)
35
36
-[Underhållare](#underhållare)
36
37
-[Krediter och referenser](#krediter-och-referenser)
37
38
38
-
## Installation och krav
39
+
## Instruktioner för att komma igång snabbt
39
40
40
-
Det enklaste sättet att installera RAP-LP är genom att använda [npm](https://www.npmjs.com/):
41
+
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`.
41
42
42
-
1. Klona ned projektet från senaste release, gärna via latest release tag.
43
-
2. Installera alla beroenden:
43
+
### NPM
44
+
> Notera: Att GitHub Packages (npm) kräver authentisering.<br>
45
+
> Konfigurera `.npmrc` mot rätt registry och scope, antingen globalt eller lokalt för enskilda projekt - `@diggsweden:registry=https://npm.pkg.github.com`<br>
46
+
> Om du saknar inloggning med GitHub Personal access token (PAT), se [FAQ](#hur-skapar-jag-ett-github-personal-access-token-pat).
47
+
48
+
> Notera: Att `<version>` byts ut mot önskad version av verktyget, oftast senaste release tag. För mer information se [versioner](#versioner).
44
49
50
+
#### Installera globalt med npm:
45
51
```bash
46
-
npm install
52
+
npm i -g @diggsweden/rest-api-profil-lint-processor@<version>
53
+
raplp -f openapi.yaml
47
54
```
55
+
> Notera: Att en omstart av terminal kan behövas för att `raplp` ska kunna användas som kommando.
48
56
49
-
## Instruktioner för att komma igång snabbt
57
+
#### Installera lokalt som `npm run` script
58
+
59
+
Installera och lägg som `devDependencies`:
60
+
61
+
```
62
+
npm i --save-dev @diggsweden/rest-api-profil-lint-processor@<version>
63
+
```
64
+
65
+
Lägg till ett [`npm run` script](https://docs.npmjs.com/cli/run-script) i din `package.json` med rätt sökväg till filen du vill validera:
66
+
67
+
```json
68
+
{
69
+
"scripts": {
70
+
"lint-processor": "raplp -f openapi.yaml"
71
+
}
72
+
}
73
+
```
50
74
51
-
Använd det här kommandot för att köra applikationen mot en YAML-fil:
1. Klona ned projektet, gärna från senaste release tag.
103
+
2. Installera alla beroenden:
104
+
105
+
```bash
106
+
npm install
107
+
npm start -- -f openapi.yaml
108
+
```
109
+
> Notera: Att alla kommandon lokalt körs med `npm start --`.
110
+
63
111
## Versioner
64
-
Senaste release tag ska alltid vara stabil och testad, vilket gör den till den föredragna versionen för att nyttja verktyget.
112
+
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.
113
+
114
+
**Stabila versioner**<br>
115
+
[Release](https://github.com/diggsweden/rest-api-profil-lint-processor/releases) ska alltid vara stabil och testad, vilket gör den till den föredragna versionen för att nyttja verktyget.<br>
116
+
Dessa versioner är taggade med `vX.X.X` utan något suffix.
117
+
118
+
**Pre-release- och testversioner**<br>
119
+
Pre-release-versioner är taggade med följande suffix:
120
+
- alpha → tidig testversion, ofta instabil
121
+
- beta → mer testad, men fortfarande pre-release
122
+
- rc → nära färdigställande, stabil release candidate
123
+
124
+
Rena testversioner är taggade med `vX.X.X-dev` följt av namnet på den branchen.<br>
125
+
Dessa versioner är byggda för att testa funktionalitet som är under utveckling.
65
126
66
-
Main och pre-releaser används med reservation för att all funktionalitet inte är garanterat stabil och testad.
### Validering som sparar information om regelutfall i en Excel-fil
121
200
122
-
För att spara information om regelutfall från diagnostiseringen till en avstämningsfil i Excel, lägg till --dex.
123
-
124
-
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.
201
+
För att spara information om regelutfall från diagnostiseringen till en avstämningsfil i Excel, lägg till `--dex`.<br>
202
+
Om en specifik sökväg till avstämningsfilen ska anges, kan denna läggas till.<br>
203
+
Om ingen sökväg anges, genererar verktyget automatiskt en ny avstämningsfil i den katalog där det körs.
125
204
126
-
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.
205
+
[Avstämningsfilen](document/Avstaemning_REST_API_profil_v_1_2_0_0.xlsx) 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.
127
206
128
207
**Exempel utan sökväg till avstämningsfil i Excel**
129
208
130
209
```bash
131
-
npm start -- -f apis/dok-api.yaml --dex
210
+
raplp -f openapi.yaml --dex
132
211
```
133
212
134
213
**Exempel med sökväg till avstämningsfil i Excel**
För att visa aktuell version av verktyget, lägg till `--version`
142
221
143
-
**Exempel**
144
-
145
222
```bash
146
-
npm start -- --version
223
+
raplp --version
147
224
```
148
225
149
226
### Visa hjälp
150
227
151
228
```bash
152
-
npm start -- --help
229
+
raplp --help
153
230
```
154
231
155
-
### Användning via podman/docker
156
-
157
-
I en terminal kör:
158
-
```bash
159
-
podman run --rm -it -v $(pwd):/<PATH> ghcr.io/diggsweden/rest-api-profil-lint-processor:<VERSION X.X.X> -f <PATH>/<YAML_FILE>
160
-
```
161
-
* Där \<PATH> motsvarar den path i containern som du vill att nuvarande katalog \$(pwd) mountas in i, containern får tillgång till dina filer i \$(pwd).
162
-
* Där \<YAML_FILE> motsvarar den filen som du vill applicera valideringen på.
163
-
* Där \<VERSION> mostsvarar den version av rest-api-profilen som du vill nyttja.
Vid eventuella fel och du inte hittar rap-lp-error.log kan du behöva köra kommandot via containern enligt den alternativa instruktionen nedan. Se till att containern har rättigheter att skriva till den katalog som du mountar, se [Skrivåtkomst till mount från container](#skrivåtkomst-till-mount-från-container).
171
-
172
-
#### Alternativ att köra ifrån containern
173
-
1. Starta en podman container:
174
-
- podman run --rm -it --entrypoint /bin/sh -v $(pwd):/\<PATH> ghcr.io/diggsweden/rest-api-profil-lint-processor:0.3.0
175
-
2. Kör din validering ifrån containern:
176
-
- npm start -- -f \<PATH-TO-FILE>
177
-
3. Lägg på önskade flaggor enligt tidigare exempel.
178
-
179
-
Exempel:
180
-
```bash
181
-
$ podman run --rm -it --entrypoint /bin/sh -v $(pwd):/apis ghcr.io/diggsweden/rest-api-profil-lint-processor:0.3.0
Vill du veta mer om de specifika reglerna som verktyget tillämpar, se avsnittet [GUIDELINES](GUIDELINES.md) för detaljer.
217
234
218
235
219
236
### Förklaring av översikt för regelutfall
220
237
221
-
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.
238
+
Om man väljer att köra verktyget i console läge, så kommer diagnostiseringsinformationen på stdout.<br>
239
+
I denna så kommer en sammanställning av det totala regelutfallet att visas.
222
240
223
241
- Verkställda och godkända regler:
224
242
- OK = Krav bedömt och hanterat för att möta kravet
@@ -231,7 +249,9 @@ Om man väljer att köra verktyget i console läge, så kommer diagnostiseringsi
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.
252
+
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.<br>
253
+
Däremot är kravet för regeln DOK.03 inte godkänt, vilket innebär att API:et inte möter detta krav.<br>
254
+
Dessutom framgår det att reglerna SAK.10 och DOK.01 inte är tillämpade för det aktuella API:et.
235
255
236
256
**Förklaring av detaljering för regelutfall:**
237
257
@@ -248,9 +268,13 @@ Tillsammans med diagnostiseringsinformationen följer en detaljerad beskrivning
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.
271
+
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.<br>
272
+
Kravet har bedömts ha allvarlighetsgraden Error eftersom API:et bryter mot ett SKALL/SKALL INTE-krav i REST API-profilen.<br>
273
+
Det finns också information om var i den aktuella OpenAPI-specifikationen problemet återfinns.
252
274
253
-
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.
275
+
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.<br>
276
+
Kravet har bedömts ha allvarlighetsgraden Warning eftersom API:et bryter mot ett BÖR/BÖR INTE-krav i REST API-profilen.<br>
277
+
Även här finns information om var i den aktuella OpenAPI-specifikationen problemet återfinns.
254
278
255
279
## Begränsningar
256
280
@@ -260,9 +284,29 @@ Vidare framgår det att kravet för regeln DOK.03 inte är godkänt och att det
260
284
261
285
Om du har frågor, funderingar, buggrapporter etc, vänligen kontakta [Digg - Agency for Digital Government](https://www.digg.se/)
262
286
287
+
## FAQ
288
+
### Hur skapar jag ett GitHub Personal Access Token (PAT)?
289
+
1. Gå till GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token → Generate new token (classic).
290
+
2. Sätt en beskrivning för ditt token under `Note` och ett utgångsdatum under `Expiration` (ha utgångsdatum!).
291
+
3. Select scopes → read:packages
292
+
4. Skapa token → kopiera värdet direkt (visas bara en gång).
293
+
294
+
```bash
295
+
npm login --registry=https://npm.pkg.github.com
296
+
# username: ditt GitHub-användarnamn
297
+
# password: GitHub PAT med read:packages
298
+
```
299
+
300
+
```bash
301
+
podman login ghcr.io
302
+
# username: ditt GitHub-användarnamn
303
+
# password: GitHub PAT med read:packages
304
+
```
305
+
263
306
## Bidra
264
307
265
-
Om du vill bidra till projektet, vänligen följ instruktionerna i avsnittet [Contributing](CONTRIBUTING.md).
308
+
Om du vill bidra till projektet, vänligen följ instruktionerna i avsnittet [Contributing](CONTRIBUTING.md).<br>
309
+
För utvecklare finns det mer information i avsnittet [Development](development/DEVELOPMENT.md).
0 commit comments