From 9d77ad52769783e08190df31cd4d16fd9702fc94 Mon Sep 17 00:00:00 2001 From: derberg Date: Wed, 27 May 2020 13:35:51 +0200 Subject: [PATCH 1/4] refactor: remove streetlight example for testing --- docs/authoring.md | 5 + test/docs/dummy.yml | 247 +++++++++++++++++++++++++++ test/generator.test.js | 2 +- test/templateConfigValidator.test.js | 6 +- 4 files changed, 256 insertions(+), 4 deletions(-) create mode 100644 test/docs/dummy.yml diff --git a/docs/authoring.md b/docs/authoring.md index f1774f940..320834dac 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -2,6 +2,10 @@ The AsyncAPI generator has been built with extensibility in mind. The package uses a set of default templates to let you generate documentation and code. However, you can create and use your own templates. In this section, you learn how to create your own one. +To work on a template, you need an AsyncAPI specification file that you can use for testing. For this purpose, you can use [this](test/docs/dummy.yml) dummy file as it's purpose is to cover as many features of AsyncAPI as possible. + +> In case you find some features missing or other possible improvements in the dummy file, suggest changes. The goal is to build a file that all templates can use and check their specification features coverage. + ## Common assumptions 1. A template is a directory in your file system. @@ -17,6 +21,7 @@ The AsyncAPI generator has been built with extensibility in mind. The package us - `asyncapi` that is a parsed spec file object. Read the [API](https://github.com/asyncapi/parser-js/blob/master/API.md#AsyncAPIDocument) of the Parser to understand to what structure you have access in this parameter. - `originalAsyncAPI` that is an original spec file before it is parsed. - `params` that contains the parameters provided when generating. + ## File templates It is possible to generate files for each specific object in your AsyncAPI documentation. diff --git a/test/docs/dummy.yml b/test/docs/dummy.yml new file mode 100644 index 000000000..bbac6de6a --- /dev/null +++ b/test/docs/dummy.yml @@ -0,0 +1,247 @@ +asyncapi: '2.0.0' + +externalDocs: + description: Find more info here + url: https://www.asyncapi.com + +info: + title: Dummy example with all spec features included + version: '0.0.1' + description: | + This is an example of AsyncAPI specification file that is suppose to include all possible features of the AsyncAPI specification. Do not use it on production. + + It's goal is to support development of documentation and code generation with the [AsyncAPI Generator](https://github.com/asyncapi/generator/) and [Template projects](https://github.com/search?q=topic%3Aasyncapi+topic%3Agenerator+topic%3Atemplate) + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0 + contact: + name: API Support + url: http://www.asyncapi.com/support + email: info@asyncapi.io + x-twitter: '@AsyncAPISpec' + +tags: + - name: root-tag1 + externalDocs: + description: External docs description 1 + url: https://www.asyncapi.com/ + - name: root-tag2 + description: Description 2 + externalDocs: + url: "https://www.asyncapi.com/" + - name: root-tag3 + - name: root-tag4 + description: Description 4 + - name: root-tag5 + externalDocs: + url: "https://www.asyncapi.com/" + +servers: + dummy-mqtt: + url: mqtt://localhost + protocol: mqtt + description: dummy MQTT broker + bindings: + mqtt: + clientId: guest + cleanSession: true + dummy-amqp: + url: amqp://localhost:{port} + protocol: amqp + description: dummy AMQP broker + protocolVersion: "0.9.1" + variables: + port: + enum: + - '15672' + - '5672' + security: + - user-password: [] + dommy-kafka: + url: http://localhost:{port} + protocol: kafka + description: dummy Kafka broker + variables: + port: + default: '9092' + +defaultContentType: application/json + +channels: + dummy/channel/with/{dummy}/parameter/create: + description: Dummy channel description. + parameters: + dummy: + $ref: '#/components/parameters/dummy' + publish: + summary: Inform whenever something dummy is created. + description: | + Longer description. + + Still dummy though. + operationId: receiveNewDummyInfo + tags: + - name: oparation-tag1 + externalDocs: + description: External docs description 1 + url: https://www.asyncapi.com/ + - name: oparation-tag2 + description: Description 2 + externalDocs: + url: "https://www.asyncapi.com/" + - name: oparation-tag3 + - name: oparation-tag4 + description: Description 4 + - name: oparation-tag5 + externalDocs: + url: "https://www.asyncapi.com/" + traits: + - $ref: '#/components/operationTraits/kafka' + message: + $ref: '#/components/messages/dummyCreated' + + dummy/channel/without/parameter: + bindings: + amqp: + is: routingKey + subscribe: + operationId: receiveSystemInfo + message: + $ref: '#/components/messages/dummyInfo' + +components: + messages: + dummyCreated: + name: dummyCreated + title: Dummy created message + summary: This is just a dummy create message + tags: + - name: message-tag1 + externalDocs: + description: External docs description 1 + url: https://www.asyncapi.com/ + - name: message-tag2 + description: Description 2 + externalDocs: + url: "https://www.asyncapi.com/" + - name: message-tag3 + - name: message-tag4 + description: Description 4 + - name: message-tag5 + externalDocs: + url: "https://www.asyncapi.com/" + headers: + type: object + properties: + my-custom-app-header: + type: string + payload: + $ref: "#/components/schemas/dummyCreated" + dummyInfo: + name: dummyInfo + title: Dummy system info + summary: This is just a dummy info message + description: | + More description for a dummy message. + + It is a dummy system info message. + traits: + - $ref: '#/components/messageTraits/commonHeaders' + payload: + $ref: "#/components/schemas/dummyInfo" + examples: + - one: + prop1: option1 + sentAt: 2020-01-26T13:00:00Z + - two: + prop1: option1 + sentAt: 2020-01-31T13:24:53Z + + schemas: + dummyCreated: + type: object + properties: + prop1: + type: integer + minimum: 0 + description: Dummy prop1 + prop2: + type: string + description: Dummy prop2 + sentAt: + $ref: "#/components/schemas/sentAt" + additionalProperties: false + dummyInfo: + type: object + properties: + prop1: + type: string + enum: + - option1 + - option2 + description: Dummy prop1 + sentAt: + $ref: "#/components/schemas/sentAt" + sentAt: + type: string + format: date-time + description: Date and time when the message was sent. + + securitySchemes: + user-password: + type: userPassword + apiKey: + type: apiKey + in: user + description: Provide your API key as the user and leave the password empty. + supportedOauthFlows: + type: oauth2 + description: Flows to support OAuth 2.0 + flows: + implicit: + authorizationUrl: 'https://authserver.example/auth' + scopes: + 'dummy:created': Ability to create dummy message + 'dymmy:read': Ability to read dummy info + password: + tokenUrl: 'https://authserver.example/token' + scopes: + 'dummy:created': Ability to create dummy message + 'dymmy:read': Ability to read dummy info + clientCredentials: + tokenUrl: 'https://authserver.example/token' + scopes: + 'dummy:created': Ability to create dummy message + 'dymmy:read': Ability to read dummy info + authorizationCode: + authorizationUrl: 'https://authserver.example/auth' + tokenUrl: 'https://authserver.example/token' + refreshUrl: 'https://authserver.example/refresh' + scopes: + 'dummy:created': Ability to create dummy message + 'dymmy:read': Ability to read dummy info + openIdConnectWellKnown: + type: openIdConnect + openIdConnectUrl: 'https://authserver.example/.well-known' + + parameters: + dummy: + description: The ID of the new dummy message. + schema: + type: string + + messageTraits: + commonHeaders: + headers: + type: object + properties: + my-app-header: + type: integer + minimum: 0 + maximum: 100 + + operationTraits: + kafka: + bindings: + kafka: + clientId: my-app-id \ No newline at end of file diff --git a/test/generator.test.js b/test/generator.test.js index cfbb78a25..536260233 100644 --- a/test/generator.test.js +++ b/test/generator.test.js @@ -3,7 +3,7 @@ const fs = require('fs'); const path = require('path'); const Generator = require('../lib/generator'); -const streetlightYAML = fs.readFileSync(path.resolve(__dirname, './docs/streetlights.yml'), 'utf8'); +const streetlightYAML = fs.readFileSync(path.resolve(__dirname, './docs/dummy.yml'), 'utf8'); jest.mock('../lib/utils'); jest.mock('../lib/filtersRegistry'); diff --git a/test/templateConfigValidator.test.js b/test/templateConfigValidator.test.js index 1025afa92..2cecd9235 100644 --- a/test/templateConfigValidator.test.js +++ b/test/templateConfigValidator.test.js @@ -1,7 +1,7 @@ const { validateTemplateConfig } = require('../lib/templateConfigValidator'); const fs = require('fs'); const path = require('path'); -const streetlightYAML = fs.readFileSync(path.resolve(__dirname, './docs/streetlights.yml'), 'utf8'); +const streetlightYAML = fs.readFileSync(path.resolve(__dirname, './docs/dummy.yml'), 'utf8'); jest.mock('../lib/utils'); @@ -91,13 +91,13 @@ describe('Template Configuration Validator', () => { it('Validation throw error if given protocol is not supported by template', () => { const templateParams = { - server: 'production' + server: 'dummy-mqtt' }; const templateConfig = { supportedProtocols: ['myprotocol'] }; - expect(() => validateTemplateConfig(templateConfig, templateParams, asyncapiDocument)).toThrow('Server \"production\" uses the mqtt protocol but this template only supports the following ones: myprotocol.'); + expect(() => validateTemplateConfig(templateConfig, templateParams, asyncapiDocument)).toThrow('Server \"dummy-mqtt\" uses the mqtt protocol but this template only supports the following ones: myprotocol.'); }); it('Validation throw error if subject in condition files is not string', () => { From 20456bd0b3a11cfaf75970e3e4cf43a3f74550a5 Mon Sep 17 00:00:00 2001 From: derberg Date: Wed, 27 May 2020 13:43:23 +0200 Subject: [PATCH 2/4] chore: remove streetlights file --- docs/authoring.md | 2 +- test/docs/streetlights.yml | 204 ------------------------------------- 2 files changed, 1 insertion(+), 205 deletions(-) delete mode 100644 test/docs/streetlights.yml diff --git a/docs/authoring.md b/docs/authoring.md index 320834dac..60c7134a4 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -2,7 +2,7 @@ The AsyncAPI generator has been built with extensibility in mind. The package uses a set of default templates to let you generate documentation and code. However, you can create and use your own templates. In this section, you learn how to create your own one. -To work on a template, you need an AsyncAPI specification file that you can use for testing. For this purpose, you can use [this](test/docs/dummy.yml) dummy file as it's purpose is to cover as many features of AsyncAPI as possible. +To work on a template, you need an AsyncAPI specification file that you can use for testing. For this purpose, you can use [this](test/docs/dummy.yml) dummy file as it's purpose is to cover as many features of AsyncAPI as possible. Do not copy this file to your template but use it directly from this repo like this: `ag https://raw.githubusercontent.com/asyncapi/generator/master/test/docs/dummy.yml ./your-template` > In case you find some features missing or other possible improvements in the dummy file, suggest changes. The goal is to build a file that all templates can use and check their specification features coverage. diff --git a/test/docs/streetlights.yml b/test/docs/streetlights.yml deleted file mode 100644 index a9db12ce9..000000000 --- a/test/docs/streetlights.yml +++ /dev/null @@ -1,204 +0,0 @@ -asyncapi: '2.0.0' -info: - title: Streetlights API - version: '1.0.0' - description: | - The Smartylighting Streetlights API allows you to remotely manage the city lights. - - ### Check out its awesome features: - - * Turn a specific streetlight on/off 🌃 - * Dim a specific streetlight 😎 - * Receive real-time information about environmental lighting conditions 📈 - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0 - -servers: - production: - url: mqtt://test.mosquitto.org:{port} - protocol: mqtt - description: Test broker - variables: - port: - description: Secure connection (TLS) is available through port 8883. - default: '1883' - enum: - - '1883' - - '8883' - -defaultContentType: application/json - -channels: - smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured: - description: The topic on which measured values may be produced and consumed. - parameters: - streetlightId: - $ref: '#/components/parameters/streetlightId' - publish: - summary: Inform about environmental lighting conditions of a particular streetlight. - operationId: receiveLightMeasurement - traits: - - $ref: '#/components/operationTraits/kafka' - message: - $ref: '#/components/messages/lightMeasured' - - smartylighting/streetlights/1/0/action/{streetlightId}/turn/on: - parameters: - streetlightId: - $ref: '#/components/parameters/streetlightId' - subscribe: - operationId: turnOn - traits: - - $ref: '#/components/operationTraits/kafka' - message: - $ref: '#/components/messages/turnOnOff' - - smartylighting/streetlights/1/0/action/{streetlightId}/turn/off: - parameters: - streetlightId: - $ref: '#/components/parameters/streetlightId' - subscribe: - operationId: turnOff - traits: - - $ref: '#/components/operationTraits/kafka' - message: - $ref: '#/components/messages/turnOnOff' - - smartylighting/streetlights/1/0/action/{streetlightId}/dim: - parameters: - streetlightId: - $ref: '#/components/parameters/streetlightId' - subscribe: - operationId: dimLight - traits: - - $ref: '#/components/operationTraits/kafka' - message: - $ref: '#/components/messages/dimLight' - -components: - messages: - lightMeasured: - name: lightMeasured - title: Light measured - summary: Inform about environmental lighting conditions of a particular streetlight. - contentType: application/json - traits: - - $ref: '#/components/messageTraits/commonHeaders' - payload: - $ref: "#/components/schemas/lightMeasuredPayload" - turnOnOff: - name: turnOnOff - title: Turn on/off - summary: Command a particular streetlight to turn the lights on or off. - traits: - - $ref: '#/components/messageTraits/commonHeaders' - payload: - $ref: "#/components/schemas/turnOnOffPayload" - dimLight: - name: dimLight - title: Dim light - summary: Command a particular streetlight to dim the lights. - traits: - - $ref: '#/components/messageTraits/commonHeaders' - payload: - $ref: "#/components/schemas/dimLightPayload" - - schemas: - lightMeasuredPayload: - type: object - properties: - lumens: - type: integer - minimum: 0 - description: Light intensity measured in lumens. - x-pi: false - sentAt: - $ref: "#/components/schemas/sentAt" - turnOnOffPayload: - type: object - properties: - command: - type: string - enum: - - on - - off - description: Whether to turn on or off the light. - x-pi: false - sentAt: - $ref: "#/components/schemas/sentAt" - dimLightPayload: - type: object - properties: - percentage: - type: integer - description: Percentage to which the light should be dimmed to. - minimum: 0 - maximum: 100 - sentAt: - $ref: "#/components/schemas/sentAt" - sentAt: - type: string - format: date-time - description: Date and time when the message was sent. - - securitySchemes: - apiKey: - type: apiKey - in: user - description: Provide your API key as the user and leave the password empty. - supportedOauthFlows: - type: oauth2 - description: Flows to support OAuth 2.0 - flows: - implicit: - authorizationUrl: 'https://authserver.example/auth' - scopes: - 'streetlights:on': Ability to switch lights on - 'streetlights:off': Ability to switch lights off - 'streetlights:dim': Ability to dim the lights - password: - tokenUrl: 'https://authserver.example/token' - scopes: - 'streetlights:on': Ability to switch lights on - 'streetlights:off': Ability to switch lights off - 'streetlights:dim': Ability to dim the lights - clientCredentials: - tokenUrl: 'https://authserver.example/token' - scopes: - 'streetlights:on': Ability to switch lights on - 'streetlights:off': Ability to switch lights off - 'streetlights:dim': Ability to dim the lights - authorizationCode: - authorizationUrl: 'https://authserver.example/auth' - tokenUrl: 'https://authserver.example/token' - refreshUrl: 'https://authserver.example/refresh' - scopes: - 'streetlights:on': Ability to switch lights on - 'streetlights:off': Ability to switch lights off - 'streetlights:dim': Ability to dim the lights - openIdConnectWellKnown: - type: openIdConnect - openIdConnectUrl: 'https://authserver.example/.well-known' - - parameters: - streetlightId: - description: The ID of the streetlight. - schema: - type: string - - messageTraits: - commonHeaders: - headers: - type: object - properties: - my-app-header: - type: integer - minimum: 0 - maximum: 100 - - operationTraits: - kafka: - bindings: - kafka: - clientId: my-app-id From 33dd8348705c5dbba69631e959a45072ed3f5b62 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Wed, 27 May 2020 21:07:17 +0200 Subject: [PATCH 3/4] improve var names --- test/templateConfigValidator.test.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/test/templateConfigValidator.test.js b/test/templateConfigValidator.test.js index 2cecd9235..0de153511 100644 --- a/test/templateConfigValidator.test.js +++ b/test/templateConfigValidator.test.js @@ -1,7 +1,7 @@ const { validateTemplateConfig } = require('../lib/templateConfigValidator'); const fs = require('fs'); const path = require('path'); -const streetlightYAML = fs.readFileSync(path.resolve(__dirname, './docs/dummy.yml'), 'utf8'); +const dummyYAML = fs.readFileSync(path.resolve(__dirname, './docs/dummy.yml'), 'utf8'); jest.mock('../lib/utils'); @@ -10,7 +10,7 @@ describe('Template Configuration Validator', () => { beforeAll(async () => { const { parse } = jest.requireActual('@asyncapi/parser'); - asyncapiDocument = await parse(streetlightYAML); + asyncapiDocument = await parse(dummyYAML); }); it('Validation doesn\'t throw errors if params are not passed and template has no config', () => { @@ -146,4 +146,4 @@ describe('Template Configuration Validator', () => { expect(templateConfig.conditionalFiles['my/path/to/file.js']).toBeDefined(); }); -}); \ No newline at end of file +}); From fe7f20bee1d1319d2fb1f44b937ecd2a1730c70f Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Wed, 27 May 2020 21:09:38 +0200 Subject: [PATCH 4/4] remove streetlight var --- test/generator.test.js | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/test/generator.test.js b/test/generator.test.js index 536260233..990aca27d 100644 --- a/test/generator.test.js +++ b/test/generator.test.js @@ -3,7 +3,7 @@ const fs = require('fs'); const path = require('path'); const Generator = require('../lib/generator'); -const streetlightYAML = fs.readFileSync(path.resolve(__dirname, './docs/dummy.yml'), 'utf8'); +const dummyYAML = fs.readFileSync(path.resolve(__dirname, './docs/dummy.yml'), 'utf8'); jest.mock('../lib/utils'); jest.mock('../lib/filtersRegistry'); @@ -225,11 +225,11 @@ describe('Generator', () => { it('calls parser.parse and this.generate', async () => { const gen = new Generator('testTemplate', __dirname); gen.generate = generateMock; - await gen.generateFromString(streetlightYAML); + await gen.generateFromString(dummyYAML); expect(generateMock).toHaveBeenCalled(); expect(parserMock.parse).toHaveBeenCalled(); - expect(parserMock.parse.mock.calls[0][0]).toBe(streetlightYAML); + expect(parserMock.parse.mock.calls[0][0]).toBe(dummyYAML); expect(parserMock.parse.mock.calls[0][1]).toStrictEqual({}); }); @@ -237,10 +237,10 @@ describe('Generator', () => { const gen = new Generator('testTemplate', __dirname); const fakeOptions = { test: true }; gen.generate = generateMock; - await gen.generateFromString(streetlightYAML, fakeOptions); + await gen.generateFromString(dummyYAML, fakeOptions); expect(parserMock.parse).toHaveBeenCalled(); - expect(parserMock.parse.mock.calls[0][0]).toBe(streetlightYAML); + expect(parserMock.parse.mock.calls[0][0]).toBe(dummyYAML); expect(parserMock.parse.mock.calls[0][1]).toStrictEqual(fakeOptions); }); @@ -259,8 +259,8 @@ describe('Generator', () => { it('stores the original asyncapi document', async () => { const gen = new Generator('testTemplate', __dirname); gen.generate = generateMock; - await gen.generateFromString(streetlightYAML); - expect(gen.originalAsyncAPI).toBe(streetlightYAML); + await gen.generateFromString(dummyYAML); + expect(gen.originalAsyncAPI).toBe(dummyYAML); }); });