feat(reference): add Workflows 1.0.0 YAML parser plugin (#3572)

Author: frankkilcommins

package-lock.json

@@ -265,6 +265,20 @@ Supported media types are:
 ]
 ```
 
+#### [workflows-yaml-1](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference/src/parse/parsers/workflows-yaml-1)
+
+Wraps [@swagger-api/apidom-parser-adapter-workflows-yaml-1](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-workflows-yaml-1) package
+and is uniquely identified by `workflows-yaml-1` name.
+
+Supported media types are:
+
+```js
+[
+  'application/vnd.oai.workflows;version=1.0.0',
+  'application/vnd.oai.workflows+yaml;version=1.0.0',
+]
+```
+
 #### [api-design-systems-json](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference/src/parse/parsers/api-design-systems-json)
 
 Wraps [@swagger-api/apidom-parser-adapter-api-design-systsems-json](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-api-design-systems-json) package
@@ -353,6 +367,7 @@ returns `true` or until entire list of parser plugins is exhausted (throws error
   AsyncApiJson2Parser({ allowEmpty: true, sourceMap: false }),
   AsyncApiYaml2Parser({ allowEmpty: true, sourceMap: false }),
   WorkflowsJson1Parser({ allowEmpty: true, sourceMap: false }),
+  WorkflowsYaml1Parser({ allowEmpty: true, sourceMap: false }),
   ApiDesignSystemsJsonParser({ allowEmpty: true, sourceMap: false }),
   ApiDesignSystemsYamlParser({ allowEmpty: true, sourceMap: false }),
   JsonParser({ allowEmpty: true, sourceMap: false }),
@@ -374,7 +389,8 @@ import OpenApiJson3_1Parser from '@swagger-api/apidom-reference/parse/parsers/op
 import OpenApiYaml3_1Parser from '@swagger-api/apidom-reference/parse/parsers/openapi-yaml-3-1'
 import AsyncApiJson2Parser from '@swagger-api/apidom-reference/parse/parsers/asyncapi-json-2';
 import AsyncApiYaml2Parser from '@swagger-api/apidom-reference/parse/parsers/asyncapi-yaml-2';
-import WorkflowsJson1Parser from '@swagger-api/apidom-reference/parse/parsers/workflows-json-1'; 
+import WorkflowsJson1Parser from '@swagger-api/apidom-reference/parse/parsers/workflows-json-1';
+import WorkflowsYaml1Parser from '@swagger-api/apidom-reference/parse/parsers/workflows-yaml-1';
 import ApiDesignSystemsJsonParser from '@swagger-api/apidom-reference/parse/parsers/api-design-systems-json';
 import ApiDesignSystemsYamlParser from '@swagger-api/apidom-reference/parse/parsers/api-design-systems-json';
 import JsonParser from '@swagger-api/apidom-reference/parse/parsers/json';
@@ -392,6 +408,7 @@ options.parse.parsers = [
   AsyncApiJson2Parser({ allowEmpty: true, sourceMap: false }),
   AsyncApiYaml2Parser({ allowEmpty: true, sourceMap: false }),
   WorkflowsJson1Parser({ allowEmpty: true, sourceMap: false }),
+  WorkflowsYaml1Parser({ allowEmpty: true, sourceMap: false }),
   ApiDesignSystemsJsonParser({ allowEmpty: true, sourceMap: false }),
   ApiDesignSystemsYamlParser({ allowEmpty: true, sourceMap: false }),
   YamlParser({ allowEmpty: true, sourceMap: false }),
@@ -412,7 +429,8 @@ import OpenApiJson3_1Parser from '@swagger-api/apidom-reference/parse/parsers/op
 import OpenApiYaml3_1Parser from '@swagger-api/apidom-reference/parse/parsers/openapi-yaml-3-1'
 import AsyncApiJson2Parser from '@swagger-api/apidom-reference/parse/parsers/asyncapi-json-2';
 import AsyncApiYaml2Parser from '@swagger-api/apidom-reference/parse/parsers/asyncapi-yaml-2';
-import WorkflowsJson1Parser from '@swagger-api/apidom-reference/parse/parsers/workflows-json-2';
+import WorkflowsJson1Parser from '@swagger-api/apidom-reference/parse/parsers/workflows-json-1';
+import WorkflowsYaml1Parser from '@swagger-api/apidom-reference/parse/parsers/workflows-yaml-1';
 import ApiDesignSystemsJsonParser from '@swagger-api/apidom-reference/parse/parsers/api-design-systems-json';
 import ApiDesignSystemsYamlParser from '@swagger-api/apidom-reference/parse/parsers/api-design-systems-json';
 import JsonParser from '@swagger-api/apidom-reference/parse/parsers/json';
@@ -432,6 +450,7 @@ await parse('/home/user/oas.json', {
       AsyncApiJson2Parser({ allowEmpty: true, sourceMap: false }),
       AsyncApiYaml2Parser({ allowEmpty: true, sourceMap: false }),
       WorkflowsJson1Parser({ allowEmpty: true, sourceMap: false }),
+      WorkflowsYaml1Parser({ allowEmpty: true, sourceMap: false }),
       ApiDesignSystemsJsonParser({ allowEmpty: true, sourceMap: false }),
       ApiDesignSystemsYamlParser({ allowEmpty: true, sourceMap: false }),
       YamlParser({ allowEmpty: true, sourceMap: false }),

packages/apidom-reference/README.md

@@ -97,7 +97,12 @@
       "import": "./es/parse/parsers/workflows-json-1/index.mjs",
       "require": "./cjs/parse/parsers/workflows-json-1/index.cjs",
       "types": "./types/parse/parsers/workflows-json-1/index.d.ts"
-    },    
+    },
+    "./parse/parsers/workflows-yaml-1": {
+      "import": "./es/parse/parsers/workflows-yaml-1/index.mjs",
+      "require": "./cjs/parse/parsers/workflows-yaml-1/index.cjs",
+      "types": "./types/parse/parsers/workflows-yaml-1/index.d.ts"
+    },       
     "./parse/parsers/binary": {
       "browser": {
         "import": "./es/parse/parsers/binary/index-browser.mjs",
@@ -261,6 +266,8 @@
     "@swagger-api/apidom-parser-adapter-openapi-yaml-3-0": "^0.89.0",
     "@swagger-api/apidom-parser-adapter-openapi-yaml-3-1": "^0.89.0",
     "@swagger-api/apidom-ns-workflows-1": "^0.89.0",
+    "@swagger-api/apidom-parser-adapter-workflows-json-1": "^0.89.0",
+    "@swagger-api/apidom-parser-adapter-workflows-yaml-1": "^0.89.0",        
     "@swagger-api/apidom-parser-adapter-yaml-1-2": "^0.89.0"
   },
   "devDependencies": {
@@ -282,6 +289,8 @@
     "@swagger-api/apidom-parser-adapter-openapi-yaml-3-0": "*",
     "@swagger-api/apidom-parser-adapter-openapi-yaml-3-1": "*",
     "@swagger-api/apidom-ns-workflows-1": "*",
+    "@swagger-api/apidom-parser-adapter-workflows-json-1": "*",        
+    "@swagger-api/apidom-parser-adapter-workflows-yaml-1": "*",
     "@swagger-api/apidom-parser-adapter-yaml-1-2": "*",
     "axios-mock-adapter": "^1.21.4"
   },

packages/apidom-reference/package.json

@@ -15,6 +15,7 @@ import OpenApiYaml3_1Parser from '../parse/parsers/openapi-yaml-3-1';
 import AsyncApiJson2Parser from '../parse/parsers/asyncapi-json-2';
 import AsyncApiYaml2Parser from '../parse/parsers/asyncapi-yaml-2';
 import WorkflowsJson1Parser from '../parse/parsers/workflows-json-1';
+import WorkflowsYaml1Parser from '../parse/parsers/workflows-yaml-1';
 import JsonParser from '../parse/parsers/json';
 import YamlParser from '../parse/parsers/yaml-1-2';
 import BinaryParser from '../parse/parsers/binary/index-node';
@@ -35,6 +36,7 @@ options.parse.parsers = [
   AsyncApiJson2Parser({ allowEmpty: true, sourceMap: false }),
   AsyncApiYaml2Parser({ allowEmpty: true, sourceMap: false }),
   WorkflowsJson1Parser({ allowEmpty: true, sourceMap: false }),
+  WorkflowsYaml1Parser({ allowEmpty: true, sourceMap: false }),
   ApiDesignSystemsJsonParser({ allowEmpty: true, sourceMap: false }),
   ApiDesignSystemsYamlParser({ allowEmpty: true, sourceMap: false }),
   JsonParser({ allowEmpty: true, sourceMap: false }),

packages/apidom-reference/src/configuration/saturated.ts

@@ -0,0 +1,42 @@
+import stampit from 'stampit';
+import { pick } from 'ramda';
+import { ParseResultElement } from '@swagger-api/apidom-core';
+import { parse, mediaTypes, detect } from '@swagger-api/apidom-parser-adapter-workflows-yaml-1';
+
+import ParserError from '../../../errors/ParserError';
+import { File as IFile, Parser as IParser } from '../../../types';
+import Parser from '../Parser';
+
+const WorkflowsYaml1Parser: stampit.Stamp<IParser> = stampit(Parser, {
+  props: {
+    name: 'workflows-yaml-1',
+    fileExtensions: ['.yaml', '.yml'],
+    mediaTypes,
+  },
+  methods: {
+    async canParse(file: IFile): Promise<boolean> {
+      const hasSupportedFileExtension =
+        this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
+      const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
+
+      if (!hasSupportedFileExtension) return false;
+      if (hasSupportedMediaType) return true;
+      if (!hasSupportedMediaType) {
+        return detect(file.toString());
+      }
+      return false;
+    },
+    async parse(file: IFile): Promise<ParseResultElement> {
+      const source = file.toString();
+
+      try {
+        const parserOpts = pick(['sourceMap', 'refractorOpts'], this);
+        return await parse(source, parserOpts);
+      } catch (error: any) {
+        throw new ParserError(`Error parsing "${file.uri}"`, { cause: error });
+      }
+    },
+  },
+});
+
+export default WorkflowsYaml1Parser;

packages/apidom-reference/src/parse/parsers/workflows-yaml-1/index.ts

@@ -0,0 +1,61 @@
+workflowsSpec: 1.0.0
+info:
+    title: A pet purchasing workflow
+    summary: This workflow showcases how to purchase a pet through a sequence of API calls
+    description: |
+        This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet.
+    version: 1.0.1
+sourceDescriptions:
+- name: petStoreDescription
+  url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
+  type: openapi
+
+workflows:
+- workflowId: loginUserRetrievePet  
+  summary: Login User and then retrieve pets
+  description: This procedure lays out the steps to login a user and then retrieve pets
+  inputs: 
+      type: object
+      properties:
+          username:
+              type: string
+          password:
+              type: string
+  steps:
+  - stepId: loginStep
+    description: This step demonstrates the user login step
+    operationId: petStoreDescription.loginUser
+    parameters:
+      # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
+      - name: username
+        in: query
+        value: $inputs.username
+      - name: password
+        in: query
+        value: $inputs.password
+    successCriteria:
+      # assertions to determine step was successful
+      - condition: $statusCode == 200
+    outputs:
+      # outputs from this step
+      tokenExpires: $response.header.X-Expires-After
+      rateLimit: $response.header.X-Rate-Limit
+      sessionToken: $response.body
+  - stepId: getPetStep
+    description: retrieve a pet by status from the GET pets endpoint
+    operationRef: https://petstore3.swagger.io/api/v3/openapi.json#/paths/users/~findbystatus~1{status}/get
+    dependsOn: loginStep
+    parameters:
+      - name: status
+        in: query
+        value: 'available'
+      - name: Authorization
+        in: header
+        value: $steps.loginUser.outputs.sessionToken    
+    successCriteria:
+      - condition: $statusCode == 200
+    outputs:
+      # outputs from this step
+      availablePets: $response.body
+  outputs:
+      available: $steps.getPetStep.availablePets