Skip to content

Commit

Permalink
docs: minor readme updates
Browse files Browse the repository at this point in the history 
moving some documentation from Contributing into the Readme
  • Loading branch information
@ColinEberhardt
ColinEberhardt committed Oct 30, 2023
1 parent 936302e commit ab49363
Show file tree
Hide file tree
Showing 2 changed files with 115 additions and 112 deletions.
111 changes: 1 addition & 110 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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_

<br>

## What to include in the issue

- ### Bug
Expand All @@ -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_

<br>

## 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_

<br>

## 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 <gens> 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 <csharpPath> 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 <typescriptPath> 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 <level> 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.

<br>

# 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' ]
}
<path>\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
}
}
```

<br>

## 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
```
116 changes: 114 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -57,7 +62,8 @@ Options:
-e, --exclude <glob> A glob pattern that excludes files from the generator in the output (default: "")
-o, --output <path> The path where the generated client API will be written (default: ".")
-s, --skipValidation Skip schema validation
-l, --logLevel <level> Sets the logging level, options are: quiet ('quiet', 'q' or '0'), standard (default) ('standard', 's' or '1'), verbose ('verbose', 'v' or '2')
-l, --logLevel <level> 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
```

Expand All @@ -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
Expand Down Expand Up @@ -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' ]
}
<path>\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
}
}
```

0 comments on commit ab49363

Please sign in to comment.