Feature/332 dok06

GUIDELINES.md

@@ -1,7 +1,7 @@
 <!--
 SPDX-FileCopyrightText: 2025 diggsweden/rest-api-profil-lint-processor
 
-SPDX-License-Identifier: CC0-1.0 
+SPDX-License-Identifier: CC0-1.0
 -->
 
 # RAP-LP Open API Specification Guidelines Version 1.0.0
@@ -14,7 +14,6 @@ Utöver reglerna från REST API-profilen innehåller RAP-LP även ett regelområ
 
 Den första versionen av RAP-LP är kompatibel med REST API-profil version 1.2.0, och varje ny version av verktyget kommer att ange vilken version av profilen den är avsedd att stödja.
 
-
 ## Regelstruktur
 
 Detta dokument specificerar reglerna som verktyget tillämpar.
@@ -33,6 +32,7 @@ Detta dokument specificerar reglerna som verktyget tillämpar.
 1. [Område: Dokumentation](#område-dokumentation)
    - [ID: DOK.01](#id-dok01)
    - [ID: DOK.03](#id-dok03)
+   - [ID: DOK.06](#id-dok06)
    - [ID: DOK.07](#id-dok07)
    - [ID: DOK.15](#id-dok15)
    - [ID: DOK.17](#id-dok17)
@@ -79,12 +79,12 @@ Detta dokument specificerar reglerna som verktyget tillämpar.
    - [ID: SAK.16](#id-sak16)
    - [ID: SAK.18](#id-sak18)
 10. [Område: Förutsättningar](#område-förutsättningar)
-- [ID: FOR.02](#id-for02)
 
+- [ID: FOR.02](#id-for02)
 
 ## Område: Dokumentation
 
-**Täckningsgrad: 29%**
+**Täckningsgrad: 33%**
 
 ### ID: DOK.01
 
@@ -147,6 +147,38 @@ Regeln förutsätter att det finns en förekomst av objektet `info` med underlig
 
 ---
 
+### ID: DOK.06
+
+**Krav:** Dokumentationen BÖR finnas på både svenska och engelska.
+
+**Typ:** BÖR
+
+**JSON Path Plus-uttryck:**
+
+```
+$.info.description
+```
+
+**Förklaring:**
+Regeln förutsätter att det finns en förekomst av objektet `info` med underliggande struktur:
+
+- info
+  - description
+
+`description` förväntas dessutom innehålla dokumentation på både svenska och engelska. Detta görs i nuläget genom att försöka matcha enskilda ord mot de som finns i [ordlistorna.](rulesets/constants/CommonWords.ts)
+
+**Exempel:**
+
+![Exempelbild som visar att pipesymbolen kan användas för att skriva beskrivningen över flera rader i en OpenAPI Description](images/dok6-1.png)
+
+_Pipesymbolen kan med fördel användas när beskrivningen sträcker sig över flera rader eller stycken._
+
+![Exempelbild som visar att större än-tecknet kan använndas för att skriva beskrivningen över flera rader i en OpenAPI Description](images/dok6-2.png)
+
+_Större än-tecknet kan också användas när beskrivningen sträcker sig över flera rader eller stycken._
+
+---
+
 ### ID: DOK.07
 
 **Krav:** Dokumentationen av ett API BÖR innehålla övergripande information om API:et.
@@ -1063,6 +1095,7 @@ Regeln kontrollerar, förutsatt att typen av säkerhetsschema är ett oauth2, at
 I exemplet ovan så kommer regeln att ge ett negativt utfall eftersom clientCredentials fälten tokenUrl samt refreshUrl är specificerat med http.
 
 ---
+
 ## Område: Förutsättningar
 
 **Täckningsgrad: 100%**

REUSE.toml

@@ -31,6 +31,8 @@ path = [
     "images/dok19.png",
     "images/dok20.png",
     "images/dok3.png",
+    "images/dok6-1.png",
+    "images/dok6-2.png",
     "images/dok7.png",
     "images/dot1-2.png",
     "images/dot1.png",

apis/dok-api.yaml

@@ -6,7 +6,14 @@ openapi: '3.0.0'
 info:
   version: 1.0.0
   title: AME
-  description: API message
+  description: >
+    När dokumentationen består av flera stycken kan också större än-tecknet användas.
+    Då ersätts radbrytningar med mellanslag.
+    Tomma rader bevaras däremot som styckeavgränsare.
+
+    When the documentation consists of multiple paragraphs, the greater-than operator can be used.
+    This converts line breaks into spaces.
+    However, empty lines are preserved as paragraph separators.
   termsOfService: http://swagger.io/terms/
   contact:
     name: Swagger API Team

rulesets/DokRules.ts

@@ -8,6 +8,7 @@ import { truthy, falsy, pattern } from '@stoplight/spectral-functions';
 import { DiagnosticSeverity } from '@stoplight/types';
 import { Dok03Base } from './rulesetUtil.ts';
 import { Dok15Base } from './rulesetUtil.ts';
+import { commonEnglishWords, commonSwedishWords } from './constants/CommonWords.ts';
 const moduleName: string = 'DokRules.ts';
 
 export class Dok15Get extends Dok15Base {
@@ -133,6 +134,54 @@ export class Dok20 extends BaseRuleset {
   }
   severity = DiagnosticSeverity.Error;
 }
+export class Dok06 extends BaseRuleset {
+  static customProperties: CustomProperties = {
+    område: 'Dokumentation',
+    id: 'DOK.06',
+  };
+  given = '$.info.description';
+  message = 'Dokumentationen BÖR finnas på både svenska och engelska.';
+  then = [
+    {
+      function: (targetVal: string, _opts: string, paths: string[]) => {
+        const lowerCaseDescriptionList = targetVal.toLowerCase().match(/[a-zåäö]+/gi) || [];
+
+        const containsEnglish = lowerCaseDescriptionList.some((word) => commonEnglishWords.includes(word));
+        const containsSwedish = lowerCaseDescriptionList.some((word) => commonSwedishWords.includes(word));
+
+        if (!containsEnglish || !containsSwedish) {
+          return [
+            {
+              message: this.message,
+              severity: this.severity,
+              paths: paths,
+            },
+          ];
+        } else {
+          return [];
+        }
+      },
+    },
+    {
+      function: (targetVal: string, _opts: string, paths: string[]) => {
+        this.trackRuleExecutionHandler(
+          JSON.stringify(targetVal, null, 2),
+          _opts,
+          paths,
+          this.severity,
+          this.constructor.name,
+          moduleName,
+          Dok06.customProperties,
+        );
+      },
+    },
+  ];
+  constructor() {
+    super();
+    super.initializeFormats(['OAS3']);
+  }
+  severity = DiagnosticSeverity.Warning;
+}
 export class Dok07 extends BaseRuleset {
   static customProperties: CustomProperties = {
     område: 'Dokumentation',

rulesets/constants/CommonWords.ts

@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: 2025 diggsweden/rest-api-profil-lint-processor
+//
+// SPDX-License-Identifier: EUPL-1.2
+
+export const commonEnglishWords = [
+  'and',
+  'to',
+  'the',
+  'is',
+  'in',
+  'that',
+  'for',
+  'on',
+  'with',
+  'but',
+  'of',
+  'has',
+  'if',
+  'we',
+  'it',
+  'they',
+  'was',
+  'from',
+  'by',
+  'request',
+  'response',
+  'resource',
+  'call',
+  'access',
+  'authentication',
+  'authorization',
+  'error',
+  'update',
+  'create',
+  'delete',
+  'retrieve',
+  'example',
+  'header',
+  'body',
+  'parameters',
+  'key',
+  'description',
+  'password',
+  'security',
+  'requests',
+  'result',
+];
+
+export const commonSwedishWords = [
+  'och',
+  'att',
+  'i',
+  'det',
+  'som',
+  'är',
+  'för',
+  'på',
+  'med',
+  'men',
+  'en',
+  'av',
+  'har',
+  'om',
+  'vi',
+  'den',
+  'de',
+  'var',
+  'från',
+  'till',
+  'begäran',
+  'svar',
+  'resurs',
+  'anrop',
+  'åtkomst',
+  'autentisering',
+  'behörighet',
+  'felmeddelande',
+  'uppdatera',
+  'skapa',
+  'ta bort',
+  'hämta',
+  'förfrågan',
+  'objekt',
+  'rubrik',
+  'kropp',
+  'nyckel',
+  'beskrivning',
+  'lösenord',
+  'säkerhet',
+  'förfrågningar',
+  'resultat',
+];

tests/dok.test.ts

@@ -80,6 +80,55 @@ testRule('Dok20', [
     ],
   },
 ]);
+testRule('Dok06', [
+  {
+    name: 'giltigt testfall',
+    document: {
+      openapi: '3.1.0',
+      info: { version: '1.0', description: 'Här finns det dokumentation på svenska and english.' },
+    },
+    errors: [],
+  },
+  {
+    name: 'ogiltigt testfall - endast svenska',
+    document: {
+      openapi: '3.1.0',
+      info: { version: '1.0', description: 'Detta är på svenska' },
+    },
+    errors: [
+      {
+        message: 'Dokumentationen BÖR finnas på både svenska och engelska.',
+        severity: DiagnosticSeverity.Warning,
+      },
+    ],
+  },
+  {
+    name: 'ogiltigt testfall - endast engelska',
+    document: {
+      openapi: '3.1.0',
+      info: { version: '1.0', description: 'This is in english' },
+    },
+    errors: [
+      {
+        message: 'Dokumentationen BÖR finnas på både svenska och engelska.',
+        severity: DiagnosticSeverity.Warning,
+      },
+    ],
+  },
+  {
+    name: 'ogiltigt testfall - båda språken med sammansatta ord',
+    document: {
+      openapi: '3.1.0',
+      info: { version: '1.0', description: 'Härfinnsdetdokumentationpåsvenskaandenglish.' },
+    },
+    errors: [
+      {
+        message: 'Dokumentationen BÖR finnas på både svenska och engelska.',
+        severity: DiagnosticSeverity.Warning,
+      },
+    ],
+  },
+]);
 testRule('Dok07', [
   {
     name: 'giltigt testfall',

tests/util/rulesetTest.ts

@@ -57,6 +57,7 @@ const ruleTypes = [
   FnsRules.Fns07,
   FnsRules.Fns06,
   DokRules.Dok20,
+  DokRules.Dok06,
   DokRules.Dok07,
   FelRules.Fel01,
   FelRules.Fel02,