diff --git a/GUIDELINES.md b/GUIDELINES.md index ac43fb9a..51cfdcc3 100644 --- a/GUIDELINES.md +++ b/GUIDELINES.md @@ -1,7 +1,7 @@ # 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%** diff --git a/REUSE.toml b/REUSE.toml index 59c9b9d6..17aa4805 100644 --- a/REUSE.toml +++ b/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", diff --git a/apis/dok-api.yaml b/apis/dok-api.yaml index 519be7da..0e452ff6 100644 --- a/apis/dok-api.yaml +++ b/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 diff --git a/images/dok6-1.png b/images/dok6-1.png new file mode 100644 index 00000000..593ba55e Binary files /dev/null and b/images/dok6-1.png differ diff --git a/images/dok6-2.png b/images/dok6-2.png new file mode 100644 index 00000000..7a6dde6a Binary files /dev/null and b/images/dok6-2.png differ diff --git a/rulesets/DokRules.ts b/rulesets/DokRules.ts index b5b1bd93..050a67d3 100644 --- a/rulesets/DokRules.ts +++ b/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', diff --git a/rulesets/constants/CommonWords.ts b/rulesets/constants/CommonWords.ts new file mode 100644 index 00000000..d884ec02 --- /dev/null +++ b/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', +]; diff --git a/tests/dok.test.ts b/tests/dok.test.ts index 391d2f2b..d9a07250 100644 --- a/tests/dok.test.ts +++ b/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', diff --git a/tests/util/rulesetTest.ts b/tests/util/rulesetTest.ts index 3e6def10..800ccbd7 100644 --- a/tests/util/rulesetTest.ts +++ b/tests/util/rulesetTest.ts @@ -57,6 +57,7 @@ const ruleTypes = [ FnsRules.Fns07, FnsRules.Fns06, DokRules.Dok20, + DokRules.Dok06, DokRules.Dok07, FelRules.Fel01, FelRules.Fel02,