Merge pull request #42 from Sureshkumars/main

Add a capability to ignore specific operations from openapi by custom extensions

README.md

@@ -65,6 +65,7 @@ FLAGS
   -D, --dereference                                             resolve $ref pointers
   -H, --header=<value>...                                       add request headers when calling remote urls
   -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
+  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
   -R, --root=/                                                  override API root path
   -S, --server=http://localhost:9000...                         override servers definition
   -V, --validate                                                validate against openapi schema
@@ -110,6 +111,7 @@ FLAGS
   -D, --dereference                                             resolve $ref pointers
   -H, --header=<value>...                                       add request headers when calling remote urls
   -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
+  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
   -R, --root=/                                                  override API root path
   -S, --server=http://localhost:9000...                         override servers definition
   -V, --validate                                                validate against openapi schema
@@ -208,6 +210,7 @@ USAGE
 
 FLAGS
   -I, --inject={"info":{"version":"1.0.0"}}...  inject JSON to definition with deep merge
+  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
   -S, --server=http://localhost:9000...         override servers definition
   -T, --title=<value>                           [default: My API] The title for the API
   -d, --description=<value>                     Description for the API
@@ -274,6 +277,7 @@ FLAGS
                                                                 descriptions from definition
   -H, --header=<value>...                                       add request headers when calling remote urls
   -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
+  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
   -R, --root=/                                                  override API root path
   -S, --server=http://localhost:9000...                         override servers definition
   -U, --swagger-ui=docs                                         Swagger UI endpoint
@@ -312,6 +316,7 @@ FLAGS
   -D, --dereference                                             resolve $ref pointers
   -H, --header=<value>...                                       add request headers when calling remote urls
   -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
+  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
   -R, --root=/                                                  override API root path
   -S, --server=http://localhost:9000...                         override servers definition
   -V, --validate                                                validate against openapi schema
@@ -350,6 +355,7 @@ FLAGS
                                                                 descriptions from definition
   -H, --header=<value>...                                       add request headers when calling remote urls
   -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
+  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
   -R, --root=/                                                  override API root path
   -S, --server=http://localhost:9000...                         override servers definition
   -h, --help                                                    Show CLI help.
@@ -416,6 +422,7 @@ FLAGS
                                                                 descriptions from definition
   -H, --header=<value>...                                       add request headers when calling remote urls
   -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
+  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
   -R, --root=/                                                  override API root path
   -S, --server=http://localhost:9000...                         override servers definition
   -h, --help                                                    Show CLI help.
@@ -464,6 +471,7 @@ FLAGS
   -D, --dereference                                             resolve $ref pointers
   -H, --header=<value>...                                       add request headers when calling remote urls
   -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
+  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
   -R, --root=/                                                  override API root path
   -S, --server=http://localhost:9000...                         override servers definition
   -V, --validate                                                validate against openapi schema
@@ -498,6 +506,7 @@ FLAGS
   -D, --dereference                                             resolve $ref pointers
   -H, --header=<value>...                                       add request headers when calling remote urls
   -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
+  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
   -R, --root=/                                                  override API root path
   -S, --server=http://localhost:9000...                         override servers definition
   -V, --validate                                                validate against openapi schema
@@ -542,6 +551,7 @@ FLAGS
   -D, --dereference                                             resolve $ref pointers
   -H, --header=<value>...                                       add request headers when calling remote urls
   -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
+  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
   -R, --root=/                                                  override API root path
   -S, --server=http://localhost:9000...                         override servers definition
   -V, --validate                                                validate against openapi schema
@@ -590,6 +600,7 @@ FLAGS
   -D, --dereference                                             resolve $ref pointers
   -H, --header=<value>...                                       add request headers when calling remote urls
   -I, --inject={"info":{"version":"1.0.0"}}...                  inject JSON to definition with deep merge
+  -E, --exclude-ext=x-internal                                  Specify an openapi extension to exclude parts of the spec
   -R, --root=/                                                  override API root path
   -S, --server=http://localhost:9000...                         override servers definition
   -V, --validate                                                validate against openapi schema

__tests__/resources/openapi-with-internal.yml

@@ -0,0 +1,90 @@
+openapi: 3.0.1
+info:
+  title: My API
+  version: 1.0.0
+paths:
+  /pets:
+    get:
+      operationId: getPets
+      x-internal: true
+      responses:
+        '200':
+          $ref: '#/components/responses/ListPetsRes'
+    post:
+      operationId: createPet
+      requestBody:
+        description: Pet object to create
+        content:
+          application/json: {}
+      responses:
+        '201':
+          $ref: '#/components/responses/PetRes'
+  '/pets/{id}':
+    get:
+      operationId: getPetById
+      responses:
+        '200':
+          $ref: '#/components/responses/PetRes'
+      parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: integer
+      x-internal: true
+components:
+  schemas:
+    Pet:
+      type: object
+      properties:
+        id:
+          type: integer
+          minimum: 1
+        name:
+          type: string
+          example: Odie
+  responses:
+    ListPetsRes:
+      description: ok
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '#/components/schemas/Pet'
+    PetRes:
+      description: ok
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Pet'
+  securitySchemes:
+    ApiKeyHeaderAuth:
+      type: apiKey
+      in: header
+      name: x-apikey
+      description: API key sent as a header
+    BasicAuth:
+      type: http
+      scheme: basic
+      description: Basic username/password authentication sent in Authorization header
+    BearerAuth:
+      type: http
+      scheme: bearer
+      description: Bearer token sent in Authorization header
+    ApiKeyCookieAuth:
+      type: apiKey
+      in: cookie
+      name: apikey
+      description: API key sent as a cookie
+    ApiKeyQueryAuth:
+      type: apiKey
+      in: query
+      name: apikey
+      description: API key sent as a query parameter
+security:
+  - BasicAuth: []
+  - BearerAuth: []
+  - ApiKeyHeaderAuth: []
+  - ApiKeyCookieAuth: []
+  - ApiKeyQueryAuth: []

__tests__/resources/openapi-without-internal.yml

@@ -0,0 +1,63 @@
+openapi: 3.0.1
+info:
+  title: My API
+  version: 1.0.0
+paths:
+  /pets:
+    post:
+      operationId: createPet
+      requestBody:
+        description: Pet object to create
+        content:
+          application/json: {}
+      responses:
+        '201':
+          $ref: '#/components/responses/PetRes'
+components:
+  schemas:
+    Pet:
+      type: object
+      properties:
+        id:
+          type: integer
+          minimum: 1
+        name:
+          type: string
+          example: Odie
+  responses:
+    PetRes:
+      description: ok
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Pet'
+  securitySchemes:
+    ApiKeyHeaderAuth:
+      type: apiKey
+      in: header
+      name: x-apikey
+      description: API key sent as a header
+    BasicAuth:
+      type: http
+      scheme: basic
+      description: Basic username/password authentication sent in Authorization header
+    BearerAuth:
+      type: http
+      scheme: bearer
+      description: Bearer token sent in Authorization header
+    ApiKeyCookieAuth:
+      type: apiKey
+      in: cookie
+      name: apikey
+      description: API key sent as a cookie
+    ApiKeyQueryAuth:
+      type: apiKey
+      in: query
+      name: apikey
+      description: API key sent as a query parameter
+security:
+- BasicAuth: []
+- BearerAuth: []
+- ApiKeyHeaderAuth: []
+- ApiKeyCookieAuth: []
+- ApiKeyQueryAuth: []

src/__tests__/test-utils.ts

@@ -8,3 +8,4 @@ export const resourcePath = (...subpath: string[]) => {
 
 export const testDefinition = YAML.load(fs.readFileSync(resourcePath('openapi.yml')).toString());
 export const testDefinitionBroken = YAML.load(fs.readFileSync(resourcePath('openapi-broken.yml')).toString());
+export const testDefinitionWithoutInternal = YAML.load(fs.readFileSync(resourcePath('openapi-without-internal.yml')).toString());

src/commands/call.ts

@@ -71,6 +71,7 @@ export class Call extends Command {
         servers: flags.server,
         inject: flags.inject,
         strip: flags.strip,
+        excludeExt: flags?.['exclude-ext'],
         header,
         induceServers: true,
       });
@@ -103,7 +104,7 @@ export class Call extends Command {
         this.error('no server URL provided, use --server or modify your API spec', { exit: 1 });
       }
     }
-      
+
     // store document in context
     setContext((ctx) => ({ ...ctx, document }))
 

src/commands/info.ts

@@ -45,6 +45,7 @@ export class Info extends Command {
         strip: flags.strip,
         servers: flags.server,
         inject: flags.inject,
+        excludeExt: flags?.['exclude-ext'],
         header,
       });
     } catch (err) {

src/commands/init.ts

@@ -85,4 +85,4 @@ export class Init extends Command {
     const format = flags.format === 'json' || flags.json ? OutputFormat.JSON : OutputFormat.YAML;
     this.log(stringifyDocument({ document, format }));
   }
-}
+}

src/commands/mock.ts

@@ -22,6 +22,7 @@ export class Mock extends Command {
     ...commonFlags.servers(),
     ...commonFlags.inject(),
     ...commonFlags.strip(),
+    ...commonFlags.excludeExt(),
     ...commonFlags.header(),
     ...commonFlags.apiRoot(),
     'swagger-ui': Flags.string({ char: 'U', description: 'Swagger UI endpoint', helpValue: 'docs' }),
@@ -57,6 +58,7 @@ export class Mock extends Command {
         servers: flags.server,
         inject: flags.inject,
         strip: flags.strip,
+        excludeExt: flags?.['exclude-ext'],
         header,
         root,
         induceServers: true,

src/commands/read.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from '@oclif/test';
-import { resourcePath, testDefinition } from '../__tests__/test-utils';
+import { resourcePath, testDefinition, testDefinitionWithoutInternal } from '../__tests__/test-utils';
 import * as SwaggerParser from '@apidevtools/swagger-parser';
 import * as YAML from 'js-yaml';
 import 'chai';
@@ -14,6 +14,14 @@ describe('read', () => {
         expect(output).to.deep.equal(testDefinition);
       });
 
+    test
+      .stdout()
+      .command(['read', resourcePath('openapi-with-internal.yml'), '--exclude-ext', 'x-internal'])
+      .it('reads yaml openapi spec exluding operations and resources with x-internal', (ctx) => {
+        const output = YAML.load(ctx.stdout);
+        expect(output).to.deep.equal(testDefinitionWithoutInternal);
+      });
+
     test
       .stdout()
       .command(['read', resourcePath('openapi.json')])

src/commands/read.ts

@@ -41,6 +41,7 @@ export class Read extends Command {
         validate,
         inject: flags.inject,
         strip: flags.strip,
+        excludeExt: flags?.['exclude-ext'],
         servers: flags.server,
         header,
         root,

src/commands/redoc.ts

@@ -25,6 +25,7 @@ export class Redoc extends Command {
     ...commonFlags.serverOpts(),
     ...commonFlags.servers(),
     ...commonFlags.inject(),
+    ...commonFlags.excludeExt(),
     ...commonFlags.strip(),
     ...commonFlags.header(),
     ...commonFlags.apiRoot(),
@@ -63,6 +64,7 @@ export class Redoc extends Command {
           definition,
           servers: flags.server,
           inject: flags.inject,
+          excludeExt: flags?.['exclude-ext'],
           strip: flags.strip,
           header,
           root,

src/commands/swagger-ui.ts

@@ -32,6 +32,7 @@ export class SwaggerUI extends Command {
     ...commonFlags.servers(),
     ...commonFlags.inject(),
     ...commonFlags.strip(),
+    ...commonFlags.excludeExt(),
     ...commonFlags.swaggerUIOpts(),
     ...commonFlags.header(),
     ...commonFlags.apiRoot(),
@@ -75,6 +76,7 @@ export class SwaggerUI extends Command {
           servers: flags.server,
           inject: flags.inject,
           strip: flags.strip,
+          excludeExt: flags?.['exclude-ext'],
           header,
           root,
          });

src/commands/typegen.ts

@@ -39,6 +39,7 @@ export class Typegen extends Command {
         bundle,
         validate,
         inject: flags.inject,
+        excludeExt: flags?.['exclude-ext'],
         strip: flags.strip,
         servers: flags.server,
         header,