Feature/394 dok21 (#447)

* feat: add types for OpenAPI Specification v3.2.0

* feat: add rule DOK.21

* test: add test suite for DOK.21

* docs: add documentation for rule DOK.21

---------

Signed-off-by: Mats Johansson <extern.mats.johansson@digg.se>

Author: mmjohansson

GUIDELINES.md

@@ -41,6 +41,7 @@ Detta dokument specificerar reglerna som verktyget tillämpar.
    - [ID: DOK.17](#id-dok17)
    - [ID: DOK.19](#id-dok19)
    - [ID: DOK.20](#id-dok20)
+   - [ID: DOK.21](#id-dok21)
 2. [Område: Datum- och tidsformat](#område-datum--och-tidsformat)
    - [ID: DOT.01](#id-dot01)
    - [ID: DOT.04](#id-dot04)
@@ -93,7 +94,7 @@ Detta dokument specificerar reglerna som verktyget tillämpar.
 
 ## Område: Dokumentation
 
-**Täckningsgrad: 46%**
+**Täckningsgrad: 50%**
 
 ### ID: DOK.01
 
@@ -405,6 +406,33 @@ I exemplet ovan, så exemplifieras regeln med GET samt en POST operation, där r
 
 ---
 
+### ID: DOK.21
+
+**Krav:** Krav på autentisering SKALL anges i specifikationen.
+
+**Typ:** SKALL
+
+**JSON Path Plus-uttryck:**
+
+```
+$
+```
+
+**Förklaring:**
+Regeln förutsätter att det finns minst en förekomst av objektet `security`, antingen på rot- eller operationsnivå.
+
+**Exempel:**
+
+![Exempelbild som visar var security-objektet kan existera i en OpenAPI description](images/dok21-1.png)
+
+_Security-objektet kan existera på antingen rot- eller operationsnivå, eller båda._
+
+![Exempelbild som visar att security-objektet också kan användas när API:et saknar säkerhet](images/dok21-2.png)
+
+_Om säkerhet saknas så bör det signaleras genom att tilldela security-objektet en tom array._
+
+---
+
 ## Område: Datum- och tidsformat
 
 **Täckningsgrad: 50%**

REUSE.toml

@@ -30,6 +30,8 @@ path = [
     "images/dok17.png",
     "images/dok19.png",
     "images/dok20.png",
+    "images/dok21-1.png",
+    "images/dok21-2.png",
     "images/dok3.png",
     "images/dok6-1.png",
     "images/dok6-2.png",

images/dok21-1.png

@@ -9,6 +9,13 @@ import { DiagnosticSeverity } from '@stoplight/types';
 import { Dok03Base } from './rulesetUtil.js';
 import { Dok15Base } from './rulesetUtil.js';
 import { commonEnglishWords, commonSwedishWords } from './constants/CommonWords.js';
+import {
+  OpenAPIObject,
+  OperationObject,
+  PathItemObject,
+  PathsObject,
+  SecurityRequirementObject,
+} from '../types/openapi-3.0.js';
 const moduleName: string = 'DokRules.js';
 
 export class Dok15Get extends Dok15Base {
@@ -426,7 +433,71 @@ export class Dok19 extends BaseRuleset {
   }
   severity = DiagnosticSeverity.Error;
 }
+export class Dok21 extends BaseRuleset {
+  static customProperties: CustomProperties = {
+    område: 'Dokumentation',
+    id: 'DOK.21',
+  };
+  given = '$';
+  message = 'Krav på autentisering SKALL anges i specifikationen.';
+  then = [
+    {
+      function: (targetVal: OpenAPIObject, _opts: string, paths: string[]) => {
+        const rootSecurity: SecurityRequirementObject[] | undefined = targetVal.security;
+
+        if (rootSecurity) {
+          if (Array.isArray(rootSecurity)) {
+            return [];
+          }
+        }
+
+        const hasSecurityInAnyPath = (paths: PathsObject | undefined): boolean => {
+          if (!paths) return false;
+          return Object.values(paths).some((pathItem: PathItemObject | undefined) => {
+            if (!pathItem) return false;
+
+            return (Object.keys(pathItem) as (keyof PathItemObject)[])
+              .filter((k) => ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'].includes(k))
+              .some((k) => {
+                const op = pathItem[k] as OperationObject | undefined;
+                return op?.security;
+              });
+          });
+        };
 
+        if (hasSecurityInAnyPath(targetVal.paths)) {
+          return [];
+        }
+
+        return [
+          {
+            message: this.message,
+            severity: this.severity,
+            paths: paths,
+          },
+        ];
+      },
+    },
+    {
+      function: (targetVal: string, _opts: string, paths: string[]) => {
+        this.trackRuleExecutionHandler(
+          JSON.stringify(targetVal, null, 2),
+          _opts,
+          paths,
+          this.severity,
+          this.constructor.name,
+          moduleName,
+          Dok21.customProperties,
+        );
+      },
+    },
+  ];
+  constructor() {
+    super();
+    super.initializeFormats(['OAS3']);
+  }
+  severity = DiagnosticSeverity.Error;
+}
 export class Dok01 extends BaseRuleset {
   static customProperties: CustomProperties = {
     område: 'Dokumentation',