diff --git a/.all-contributorsrc b/.all-contributorsrc index 833fa1624..929b7eedd 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -11,8 +11,12 @@ "avatar_url": "https://avatars1.githubusercontent.com/u/4137916?v=4", "profile": "https://github.com/Tenischev", "contributions": [ + "maintenance", "doc", - "code" + "code", + "bug", + "review", + "test" ] }, { @@ -24,6 +28,15 @@ "review" ] }, + { + "login": "derberg", + "name": "Lukasz Gornicki", + "avatar_url": "https://avatars.githubusercontent.com/u/6995927?v=4", + "profile": "https://github.com/derberg/", + "contributions": [ + "review" + ] + }, { "login": "amrutprabhu", "name": "Amrut Prabhu", @@ -32,6 +45,33 @@ "contributions": [ "code" ] + }, + { + "login": "VaishnaviNandakumar", + "name": "Vaishnavi Nandakumar", + "avatar_url": "https://avatars.githubusercontent.com/u/41518119?v=4", + "profile": "https://github.com/VaishnaviNandakumar", + "contributions": [ + "code" + ] + }, + { + "login": "taotao100", + "name": "taotao100", + "avatar_url": "https://avatars.githubusercontent.com/u/7056867?v=4", + "profile": "https://github.com/taotao100", + "contributions": [ + "bug" + ] + }, + { + "login": "jbiscella", + "name": "Jacopo Biscella", + "avatar_url": "https://avatars.githubusercontent.com/u/7963565?v=4", + "profile": "https://github.com/jbiscella", + "contributions": [ + "bug" + ] } ], "contributorsPerLine": 7, diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 000000000..261eeb9e9 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index dbea56727..a6c40050c 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,51 @@ -# Java Spring generator - -[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-) - -_Use your AsyncAPI definition to generate java code to subscribe and publish messages_ +![AsyncAPI Java Spring Template](assets/github-repobanner-javaspringtemp.png) +Java Spring template for the [AsyncAPI Generator](https://github.com/asyncapi/generator). + +--- +[![License](https://img.shields.io/github/license/asyncapi/java-spring-template)](https://github.com/asyncapi/java-spring-template/blob/master/LICENSE) +[![npm](https://img.shields.io/npm/v/@asyncapi/java-spring-template?style=flat-square)](https://www.npmjs.com/package/@asyncapi/java-spring-template) +[![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-) +![downloads](https://img.shields.io/npm/dm/@asyncapi/java-spring-template?style=flat-square) +--- + + + + + +- [Usage](#usage) + * [AsyncAPI definitions](#asyncapi-definitions) + * [Supported parameters](#supported-parameters) + * [Examples](#examples) +- [Run it](#run-it) +- [Development](#development) + * [Missing features](#missing-features) +- [Contributors ✨](#contributors-%E2%9C%A8) + + ## Usage +Install AsyncAPI CLI, for details follow the [guide](https://www.asyncapi.com/tools/cli). + +```bash +npm install -g @asyncapi/cli +``` + +Generate using CLI. + +```bash +asyncapi generate fromTemplate @asyncapi/java-spring-template +``` + +You can replace `` with local path or URL pointing to [any AsyncAPI document](https://raw.githubusercontent.com/asyncapi/java-spring-template/master/tests/mocks/kafka.yml). + ### AsyncAPI definitions To have correctly generated code, your AsyncAPI file MUST define `operationId` for every operation. -In order for the generator to know what names to use for some parameters it's necessary to make use of [AsyncAPI specification bindings](https://www.asyncapi.com/docs/specifications/2.0.0/#operationBindingsObject). +In order for the generator to know what names to use for some parameters [AsyncAPI specification bindings](https://www.asyncapi.com/docs/reference/specification/v2.0.0#operationBindingsObject) SHOULD be used. +It is RECOMMENDED to not use anonymous objects in payload and components definition, if changing of data model is not possible, you MAY use `$id` to set name of element. - Complete example for Kafka is [here](tests/mocks/kafka.yml). Notice information about binding. ```yml @@ -29,21 +63,7 @@ In order for the generator to know what names to use for some parameters it's ne ``` - Complete example for MQTT is [here](tests/mocks/mqtt.yml). - -### From the command-line interface (CLI) - -```bash - Usage: ag [options] @asyncapi/java-spring-template - - Options: - - -V, --version output the version number - -o, --output directory where to put the generated files (defaults to current directory) - -p, --param additional param to pass to templates - -h, --help output usage information -``` - -#### Supported parameters +### Supported parameters |Name|Description| Required | Default | |---|---|----------|--------------------------| @@ -60,67 +80,61 @@ In order for the generator to know what names to use for some parameters it's ne |completionTimeout|Only for MQTT. The completion timeout in milliseconds for operations. The default completion timeout is 30000 milliseconds.| No | `30000` | |mqttClientId| Only for MQTT. Provides the client identifier for the MQTT server. This parameter overrides the value of the clientId if it's set in the AsyncAPI file.If both aren't provided, a default value is set.| No | | |asyncapiFileDir| Path where original AsyncAPI file will be stored.| No | `src/main/resources/api/` | -#### Examples +### Examples The shortest possible syntax: ```bash -ag asyncapi.yaml @asyncapi/java-spring-template +asyncapi generate fromTemplate asyncapi.yaml @asyncapi/java-spring-template ``` -Specify where to put the result and define poll timeout: +Specify where to put the result with `-o` option and define parameter of poll timeout with `-p` option: ```bash -ag -o ./src asyncapi.yaml -p listenerPollTimeout=5000 @asyncapi/java-spring-template +asyncapi generate fromTemplate asyncapi.yaml @asyncapi/java-spring-template -o ./src -p listenerPollTimeout=5000 ``` +## Run it -If you don't have the AsyncAPI Generator installed, you can install it like this: - -``` -npm install -g @asyncapi/generator +Go to the root folder of the generated code and run this command (you need the JDK 17): +```bash +./gradlew bootRun ``` ## Development 1. Clone the repository: - ``` + ```sh git clone https://github.com/asyncapi/java-spring-template cd java-spring-template ``` -1. Make sure template has all the dependencies: - ``` +1. Download all template dependencies: + ```sh npm install ``` -1. Install AsyncAPI Generator: +1. Make required changes in the template. +2. Run snapshot tests: + ```sh + npm test ``` - npm install -g @asyncapi/generator + If there falling tests examine diff report and make an appropriate changes in template files or snapshots. +1. Check output generation project. Install AsyncAPI Generator: ``` -1. Run generation: + npm install -g @asyncapi/cli + ``` +1. Run generation (assuming you are in template folder): ```bash # for MQTT protocol test with below - ag tests/mocks/mqtt.yml ./ --output output + asyncapi generate fromTemplate tests/mocks/mqtt.yml ./ -o output # for Kafka protocol test with below - ag tests/mocks/kafka.yml ./ --output output + asyncapi generate fromTemplate tests/mocks/kafka.yml ./ -o output ``` -1. Explore generated files in `output` directory +1. Explore generated files in `output` directory. Generated project shouldn't contain syntax or compilation errors. +Preferably generated tests should pass. > For local development, you need different variations of this command. First of all, you need to know about three important CLI flags: - `--debug` enables the debug mode. - `--watch-template` enables a watcher of changes that you make in the template. It regenerates your template whenever it detects a change. - `--install` enforces reinstallation of the template. -## Run it - -Go to the root folder of the generated code and run this command (you need the JDK1.8): -```bash -./gradlew bootRun -``` - - -Generated source contains RabbitMQ docker-compose. So you could use it to test amqp with: -```bash -docker-compose -f src/main/docker/rabbitmq.yml up -d -``` - ### Missing features See the list of features that are still missing in the component: @@ -148,9 +162,13 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d - + + + +

Semen
📖 💻
Semen
🚧📖 💻🐛👀⚠️
Francesco Nobilia
👀
Lukasz Gornicki
👀
Amrut Prabhu
💻
Vaishnavi Nandakumar
💻
taotao100
🐛 +
Jacopo Biscella
🐛
diff --git a/assets/github-repobanner-javaspringtemp.png b/assets/github-repobanner-javaspringtemp.png new file mode 100644 index 000000000..b6c710d36 Binary files /dev/null and b/assets/github-repobanner-javaspringtemp.png differ diff --git a/package.json b/package.json index aec794ab8..55536a058 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,8 @@ "scripts": { "test": "rimraf test/temp && jest --modulePathIgnorePatterns='./template'", "lint": "echo \"No linter specified yet\"", - "generate:assets": "echo 'No additional assets need to be generated at the moment'", + "generate:readme:toc": "markdown-toc -i README.md", + "generate:assets": "npm run generate:readme:toc", "bump:version": "npm --no-git-tag-version --allow-same-version version $VERSION" }, "publishConfig": { @@ -40,7 +41,8 @@ "@asyncapi/generator": "^1.14.1", "jest": "^29.6.4", "node-fetch": "^2.6.1", - "rimraf": "^2.2.8" + "rimraf": "^2.2.8", + "markdown-toc": "^1.2.0" }, "generator": { "supportedProtocols": [