From ab493631e7dbb3972c81d5361ae400614d53ecda Mon Sep 17 00:00:00 2001 From: Colin Eberhardt Date: Mon, 30 Oct 2023 14:11:29 +0000 Subject: [PATCH] docs: minor readme updates moving some documentation from Contributing into the Readme --- CONTRIBUTING.md | 111 +-------------------------------------------- README.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 115 insertions(+), 112 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8975115..7d4d551 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,8 +10,6 @@ We are actively looking for contributors to help increase the Forge's capabiliti - Does the issue already exist? _Remember to check the **open** and **closed** tickets_ -
- ## What to include in the issue - ### Bug @@ -33,117 +31,10 @@ We are actively looking for contributors to help increase the Forge's capabiliti - Is it assigned to you? _If not, post a message stating your intent so that the maintainers and other contributors know what is being developed_ - Do you understand the issue fully? _If not, ask on in the issue. We are all here to help you contribute_ -
- ## Before you submit a PR -- Link issue that PR addresses +- Provide a link to the issue that PR addresses - Link any related PRs _This could happen when forge and generator needs updating_ - Have you added tests? - Are all workflow steps passing? - Is it ready for review? _If not, create a draft_ - -
- -## Testing - -You can test openapi-forge on all of the language generators from one command: - -``` -% openapi-forge help test-generators -Usage: openapi-forge test-generators [options] - -Test language specific generators. - -Options: - -g, --generators Narrow down the generators to test. Each letter is a generator, combine letters to test multiple generators, options are: - c (CSharp), t (TypeScript) (default: "ct") - -c, --csharp Sets the location of the CSharp generator. Default is a directory called 'openapi-forge-csharp' in the same location as - openapi-forge (default: "./openapi-forge-csharp") - -t, --typescript Sets the location of the TypeScript generator. Default is a directory called 'openapi-forge-typescript' in the same - location as openapi-forge (default: "./openapi-forge-typescript") - -l, --logLevel Sets the logging level, options are: quiet ('quiet', 'q' or '0'), standard (default) ('standard', 's' or '1'), verbose - ('verbose', 'v' or '2') (default: "1") - -h, --help display help for command -``` - -### OpenAPI Forge Package - -Install openapi-forge as a global package (this is required for running the tests even if you have it git-cloned locally): - -``` -$ npm install openapi-forge --global -``` - -### Dependencies on the Forge Project - -The generators hardcode the relative path to the generate.js in order to run test-generators. Currently these must be changed manually if the path of generate.js is changed. See this issue: #158. - -### GitHub Workflows - -The Gherkin tests are run as part of Continuous Integration using `.github/workflows/test.yml`. It runs the tests on every generator, checking for the presence of a generated test results file. It does not check for passing/failing tests. See this issue: #157. - -
- -# Example directory structure for testing to work using default locations - -You can have the locations of the forge and generators in custom locations with custom names but you will need to input the relative file paths into the testing commands of the forge and generators. -Below is the file structure needed to use the testing commands with the default locations: - -``` -openapi-forge -| -|-openapi-forge-typescript -|-openapi-forge-csharp -|-openapi-forge-... -``` - -For example, run: - -``` -$ openapi-forge test-generators --format json --generators openapi-forge-csharp -``` - -You should see an output that looks like this: - -``` -{ - logLevel: '1', - format: 'json', - generators: [ 'openapi-forge-csharp' ] -} -\openapi-forge-csharp -Starting tests for generator openapi-forge-csharp -[ - { testRunStarted: { timestamp: [Object] } }, - { testCaseStarted: {} }, - { testCaseFinished: {} }, - // .... - { testRunFinished: { timestamp: [Object] } } -] -{ - "openapi-forge-csharp": { - "scenarios": 44, - "failed": 0, - "passed": 44, - "time": 47 - } -} - -``` - -
- -## Points to remember when contributing - -- The branch `gh-pages` is used to auto-generate the Github Pages webpage. DO NOT USE THIS BRANCH!!! -- This project uses [semantic-release](https://semantic-release.gitbook.io/semantic-release/) which enforces [Angular Commit Message Conventions](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format) & [Angular Verbs](https://www.conventionalcommits.org/en/v1.0.0-beta.4/). Ensure you are writing your commit messages correctly. Husky hooks have got your back for ensuring correct format but will not prevent the use of wrong types. -- The NPM scripts below can help you fix failing workflow steps: - -``` - npm run test:generators - npm run format:check:all - npm run format:write:all - npm run lint:check:all - npm run lint:write:all -``` diff --git a/README.md b/README.md index 053654e..6283188 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,12 @@ - [Schema transformation](#schema-transformation) - [Tags and API structure](#tags-and-api-structure) - [Testing](#testing) + - [Walkthrough for implementing the BDD tests for a new generator](#walkthrough-for-implementing-the-bdd-tests-for-a-new-generator) - [Formatting](#formatting) +- [OpenAPI Forge (CLI) Development](#openapi-forge-cli-development) + - [Installation and Test](#installation-and-test) + - [Tests](#tests) + - [Testing the language generators](#testing-the-language-generators) ## Design principles @@ -57,7 +62,8 @@ Options: -e, --exclude A glob pattern that excludes files from the generator in the output (default: "") -o, --output The path where the generated client API will be written (default: ".") -s, --skipValidation Skip schema validation - -l, --logLevel Sets the logging level, options are: quiet ('quiet', 'q' or '0'), standard (default) ('standard', 's' or '1'), verbose ('verbose', 'v' or '2') + -l, --logLevel Sets the logging level, options are: quiet ('quiet', 'q' or '0'), + standard (default) ('standard', 's' or '1'), verbose ('verbose', 'v' or '2') -h, --help Display help for command ``` @@ -78,7 +84,10 @@ Options: and then ``` -% openapi-forge forge https://petstore3.swagger.io/api/v3/openapi.json https://github.com/ScottLogic/openapi-forge-javascript.git --generator.moduleFormat "esmodule" +% openapi-forge forge \ + https://petstore3.swagger.io/api/v3/openapi.json \ + https://github.com/ScottLogic/openapi-forge-javascript.git \ + --generator.moduleFormat "esmodule" ``` ## Client generation @@ -304,3 +313,106 @@ Ideally the generated output should be 'neatly' formatted in an idiomatic way fo 1. Write the handlebars templates in such a way that they produce nicely formatted code. This can result in templates which are a little convoluted, however, [whitespace control](https://handlebarsjs.com/guide/expressions.html#whitespace-control) is your friend. 2. You can format the files as a post-processing step. To achieve this, add a `formatting.js` file to the root of your generator project. This will be executed as the final step of the generation process. How this is implemented is of course language-dependent. + +# OpenAPI Forge (CLI) Development + +This section describes the process for working on the CLI tool (this repo). + +## Installation and Test + +To get started, clone this repo, then follow the usual workflow: + +``` +% npm install +% npm test + PASS test/generatorOptions.test.js + PASS test/generate.test.js + PASS test/common/generatorResolver.test.js (21.788 s) + +Test Suites: 3 passed, 3 total +Tests: 17 passed, 17 total +Snapshots: 0 total +Time: 22.14 s, estimated 24 s +``` + +In order to execute the OpenAPI Forge commands locally, run `node src/index.js`. Here's an example that uses your local copy o + +``` +% node src/index.js forge \ + https://petstore3.swagger.io/api/v3/openapi.json \ + openapi-forge-javascript \ + -o api +``` + +Or alternatively install you changes globally, then run as follows: + +``` +% npm i --global +% openapi-forge +Usage: openapi-forge [options] [command] +... +``` + +Global installation is a little slower, but ensure that filepaths are representative and is less error prone. + +## Tests + +The CLI (this repo) has several different types of test: + +1. Unit tests - these are found within the `test` folder and tests the CLI / generator functionality. +2. Smoke tests - found within `smoke-test.js`, this ensures that there has not been a regression (i.e. reduced number of tests passing), between pull requests +3. BDD Generator tests - found within the `features` folder, these are the BDD-style tests that ensure a language generator works correctly. + +### Testing the language generators + +You can test all of the language generators from one command, this is useful if you make changes to the CLI tool or add / amend the BDD tests. + +After globally installing the CLI, execute `test-generators` command for any of the language generators + +``` +% openapi-forge test-generators --format json --generators openapi-forge-csharp +``` + +You'll likely want to have the language generators checked out at the same folder location: + +``` +openapi-forge +| +|-openapi-forge-typescript +|-openapi-forge-csharp +|-openapi-forge-... +``` + +For example, run: + +``` +$ openapi-forge test-generators --format json --generators openapi-forge-csharp +``` + +You should see an output that looks like this: + +``` +{ + logLevel: '1', + format: 'json', + generators: [ 'openapi-forge-csharp' ] +} +\openapi-forge-csharp +Starting tests for generator openapi-forge-csharp +[ + { testRunStarted: { timestamp: [Object] } }, + { testCaseStarted: {} }, + { testCaseFinished: {} }, + // .... + { testRunFinished: { timestamp: [Object] } } +] +{ + "openapi-forge-csharp": { + "scenarios": 44, + "failed": 0, + "passed": 44, + "time": 47 + } +} + +```