chore: adding vendor header in the parse response

Signed-off-by: Pawel Psztyc <jarrodek@gmail.com>

Author: jarrodek

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-components/amf-web-api",
   "description": "A web service parsing APIs with the AMF parser.",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "Apache-2.0",
   "main": "index.js",
   "module": "index.js",
@@ -42,6 +42,7 @@
     "@types/koa": "^2.13.4",
     "@types/koa__router": "^8.0.9",
     "@types/mocha": "^9.0.0",
+    "@types/unzipper": "^0.10.4",
     "@types/uuid": "^8.3.1",
     "chai": "^4.3.4",
     "chalk": "^4.1.2",

package.json

@@ -47,11 +47,11 @@ Notes:
 
 ### Parsing a text content
 
-This endpoints creates a task to parse the content. It does not wait for the parsing result. Instead iut returns the location of the endpoint to query for the parsing result.
+This endpoint creates a task to parse the content. It does not wait for the parsing result. Instead it returns the location of the endpoint to query for the parsing result.
 
-The `x-api-vendor` is required and it describes API vendor. It is one of the API vendors supported by the AMF parser: `RAML 0.8`, `RAML 1.0`, `OAS 2.0`, `OAS 3.0`, `AMF Graph`, `JSON Schema`, `ASYNC 2.0`.
+The `x-api-vendor` is required and it is the API vendor to use. It is one of the API vendors supported by the AMF parser: `RAML 0.8`, `RAML 1.0`, `OAS 2.0`, `OAS 3.0`, and `ASYNC 2.0`.
 
-The content type is optional and is ignored.
+The content type is optional and is ignored by the server. However, it is a good practice to keep it and set the correct value.
 
 #### Plain text request
 
@@ -91,11 +91,11 @@ Keep-Alive: timeout=5
 
 ### Parsing an API project in a zip file
 
-To parse an entire project with multiple files send the zip file as the request body.
+To parse an entire API project with multiple files send a zip file in the request body.
 
-You can set optional `x-entrypoint` header with the name of the API's main file (the entry point). When the header is not set then the server application tries to determine the best candidate using some heuristics.
+You can set an optional `x-entrypoint` header with the name of the API's main file (the entry point). When the header is not set then the server application tries to determine the best candidate using some built-in heuristics.
 
-When multiple entrypoints are found in the project then the job status endpoint returns the list of files and the client should pick one (probably involving the user). After the pick is ready the client sends the PUT request to the job status endpoint (see below).
+When multiple entrypoints are found in the project then the job status endpoint returns the list of files with the 300 status code. The client should pick one (probably involving the user). After the pick is ready the client sends the PUT request to the job status endpoint (see below).
 
 When a single endpoint is found in the API project then it is used automatically as the entrypoint. When no files are found then the process ends with an error.
 

readme.md

@@ -178,7 +178,7 @@ export class AmfParser {
     if (result.status === 'failed') {
       this.error = /** @type string */ (result.result);
     } else {
-      this.result = /** @type string */ (result.result);
+      this.result = /** @type any */ (result.result);
     }
     if (this.process.connected) {
       this.process.disconnect();

src/AmfParser.js

@@ -8,6 +8,7 @@ import { AmfParser } from './AmfParser.js';
 /** @typedef {import('../types').AmfProcessItem} AmfProcessItem */
 /** @typedef {import('../types').ProcessingStatus} ProcessingStatus */
 /** @typedef {import('../types').ParserConfiguration} ParserConfiguration */
+/** @typedef {import('../types').ApiParsingResult} ApiParsingResult */
 
 const timerSymbol = Symbol('timerSymbol');
 
@@ -141,7 +142,7 @@ export class AmfService {
   /**
    * Reads the process' computation result.
    * @param {string} key The process key.
-   * @returns {Promise<any>} The result
+   * @returns {Promise<ApiParsingResult>} The result from the process.
    */
   async getResult(key) {
     if (!this.processes.has(key)) {

src/AmfService.js

@@ -146,10 +146,12 @@ export class ApiRoutes {
     }
     if (status === 'finished') {
       const body = await this.service.getResult(key);
+      ctx.set('x-api-vendor', body.vendor);
+      const api = body.rendered;
       this.service.removeProcess(key);
       ctx.status = 200;
       ctx.type = 'application/ld+json';
-      ctx.body = body;
+      ctx.body = api;
       return;
     }
     if (status === 'running' || status === 'initialized') {

src/ApiRoutes.js

@@ -23,6 +23,7 @@ const {
 /** @typedef {import('../types').ApiProjectParseCommand} ApiProjectParseCommand */
 /** @typedef {import('../types').ParserProcessResult} ParserProcessResult */
 /** @typedef {import('../types').ParserVendors} ParserVendors */
+/** @typedef {import('../types').ApiParsingResult} ApiParsingResult */
 
 /**
  * The child process that performs the parsing job.
@@ -55,19 +56,22 @@ class AmfParserProcess {
     const { content, vendor } = command;
     const customResourceLoader = ResourceLoaderFactory.create(new ServerResourceLoader());
     try {
-      const ro = new RenderOptions().withSourceMaps().withCompactUris().withPrettyPrint();
+      const ro = new RenderOptions().withSourceMaps().withCompactUris();
       const apiConfiguration = this.getConfiguration(vendor).withRenderOptions(ro).withResourceLoader(customResourceLoader);
       const client = apiConfiguration.baseUnitClient();
       const result = await client.parseContent(content);
 
       const wac = WebAPIConfiguration.fromSpec(result.sourceSpec);
-      const waRo = new RenderOptions().withSourceMaps().withCompactUris().withPrettyPrint();
+      const waRo = new RenderOptions().withSourceMaps().withCompactUris();
       const renderConfig = wac.withRenderOptions(waRo);
       const transformed = renderConfig.baseUnitClient().transform(result.baseUnit, PipelineId.Editing);
       const rendered = client.render(transformed.baseUnit, 'application/ld+json');
       process.send(/** @type ParserProcessResult */ ({
         status: 'finished',
-        result: rendered,
+        result: /** @type ApiParsingResult */ ({
+          rendered,
+          vendor,
+        }),
       }));
     } catch (e) {
       process.send(/** @type  ParserProcessResult */ ({
@@ -84,20 +88,23 @@ class AmfParserProcess {
     const { dir, entrypoint, vendor } = command;
     const customResourceLoader = ResourceLoaderFactory.create(new ServerResourceLoader(dir));
     try {
-      const ro = new RenderOptions().withSourceMaps().withCompactUris().withPrettyPrint();
+      const ro = new RenderOptions().withSourceMaps().withCompactUris();
       const apiConfiguration = this.getConfiguration(vendor).withRenderOptions(ro).withResourceLoader(customResourceLoader);
       const client = apiConfiguration.baseUnitClient();
       const location = path.join(dir, entrypoint);
       const result = await client.parse(`file://${location}`);
 
       const wac = WebAPIConfiguration.fromSpec(result.sourceSpec).withResourceLoader(customResourceLoader);
-      const waRo = new RenderOptions().withSourceMaps().withCompactUris().withPrettyPrint();
+      const waRo = new RenderOptions().withSourceMaps().withCompactUris();
       const renderConfig = wac.withRenderOptions(waRo);
       const transformed = renderConfig.baseUnitClient().transform(result.baseUnit, PipelineId.Editing);
       const rendered = client.render(transformed.baseUnit, 'application/ld+json');
       process.send(/** @type ParserProcessResult */ ({
         status: 'finished',
-        result: rendered,
+        result: /** @type ApiParsingResult */ ({
+          rendered,
+          vendor,
+        }),
       }));
     } catch (e) {
       process.send(/** @type  ParserProcessResult */ ({

src/ParserProcess.js

@@ -43,7 +43,7 @@ export class Server {
    * 
    * @param port When specified it closes a www server on a specific port. When not it stops all running http servers.
    */
-  stopHttp(port: number): Promise<void[]>;
+  stopHttp(port?: number): Promise<void[]>;
 
   /**
    * Starts the www over SSL server on a given port.
@@ -58,7 +58,7 @@ export class Server {
    * 
    * @param port When specified it closes an ssl server on a specific port. When not it stops all running https servers.
    */
-  stopSsl(port: number): Promise<void[]>;
+  stopSsl(port?: number): Promise<void[]>;
 
   /**
    * 

src/Server.d.ts

@@ -111,6 +111,7 @@ describe('Parsing the zip file content', () => {
       const { statusCode, headers, message } = result;
       assert.equal(statusCode, 200, 'has the 200 status code');
       assert.equal(headers['content-type'], 'application/ld+json', 'has the content-type header');
+      assert.equal(headers['x-api-vendor'], 'RAML 1.0', 'has the x-api-vendor header');
       const body = JSON.parse(message.toString('utf-8'));
       assert.typeOf(body, 'object', 'has the response body');
       assert.typeOf(body['@graph'], 'array', 'has the graph response');

test/ApiProjectParsing.test.js

@@ -115,6 +115,7 @@ describe('Parsing the text content', () => {
       const { statusCode, headers, message } = result;
       assert.equal(statusCode, 200, 'has the 200 status code');
       assert.equal(headers['content-type'], 'application/ld+json', 'has the content-type header');
+      assert.equal(headers['x-api-vendor'], 'RAML 1.0', 'has the x-api-vendor header');
       const body = JSON.parse(message.toString('utf-8'));
       assert.typeOf(body, 'object', 'has the response body');
       assert.typeOf(body['@graph'], 'array', 'has the graph response');

test/TextContentParsing.test.js

@@ -85,3 +85,14 @@ export interface ParserConfiguration {
    */
   ttl?: number;
 }
+
+export interface ApiParsingResult {
+  /**
+   * The AMF ld+json model.
+   */
+  rendered: string;
+  /**
+   * The originating vendor.
+   */
+  vendor: ParserVendors;
+}