Merge pull request #179 from ynab/package-description

Include API spec version used when generating in package description

.github/workflows/publish.yml

@@ -22,7 +22,7 @@ jobs:
           git remote add gh-origin https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
       - uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 18
           registry-url: "https://registry.npmjs.org"
       - run: npm install
       - run: npm run build
@@ -50,7 +50,7 @@ jobs:
         uses: softprops/action-gh-release@v1
         with:
           tag_name: ${{ steps.push.outputs.tag-name }}
-          generate_release_notes: true     
+          generate_release_notes: true
       - name: Comment on PRs with link to release they are included in
         uses: actions/github-script@v6
         env:
@@ -76,4 +76,4 @@ jobs:
                 repo: context.repo.repo,
                 body: `The changes in this PR were just released in [${release.name}](https://github.com/${context.repo.owner}/${context.repo.repo}/releases/tag/${release.tag_name}) 🎉.`
               })
-            }          
+            }

DEVELOPMENT.md

@@ -3,11 +3,13 @@
 ## Setup
 
 - Install dependencies: `npm install`
-- Generate latest client based on OpenAPI spec:
-  - Install [OpenAPI Generator](https://openapi-generator.tech/), for macOS: `brew install openapi-generator`
-  - Run `npm run generate`
-- Run tests: `npm test`
+- Install [OpenAPI Generator](https://openapi-generator.tech/) (on macOS: `brew install openapi-generator`)
+- Build and run tests: `npm run build && npm run test`
+
+## Generating
+
+Run `npm run generate`.  This will generate the API client from the latest OpenAPI spec.  Once generated, you should open a PR and merge the changes.
 
 ## Publishing
 
-Run the "Publish" GitHub Actions workflow
+Run the "Publish" GitHub Actions workflow.  This workflow will build, version, and publish the client based on the latest code in the `main` branch.  It is expected that re-generating the client based on the latest OpenAPI spec has already been performed and changes committed.

README.md

@@ -172,6 +172,10 @@ utils.convertFromISODateString(isoDateString: string): Date;
 utils.convertMilliUnitsToCurrencyAmount(milliunits: number, currencyDecimalDigits: number): number;
 ```
 
+### Versioning
+
+The version of this client is defined in the `package.json` file and follows [semantic versioning](https://semver.org/).  The version of this client is maintained independently and does not align with the the version of YNAB API itself (which is defined in the [OpenAPI spec](https://api.ynab.com/papi/open_api_spec.yaml)).  To determine which spec version of the YNAB API was used when generating this client you can refer to the `description` field in the `package.json` file.
+
 ## License
 
 Copyright (c) 2022 You Need A Budget, LLC

package.json

@@ -1,7 +1,7 @@
 {
   "name": "ynab",
   "version": "2.6.0",
-  "description": "YNAB API Javascript (Node) Library",
+  "description": "Official JavaScript client for the YNAB API. API documentation available at https://api.ynab.com. Generated from server specification version 1.72.0",
   "author": "YNAB",
   "email": "[email protected]",
   "url": "https://api.ynab.com",
@@ -40,6 +40,7 @@
     "@types/node": "^14.0.27",
     "chai": "^4.2.0",
     "fetch-mock": "^9.10.6",
+    "js-yaml": "^4.1.0",
     "jsh": "0.55.0",
     "mocha": "^10.2.0",
     "ts-loader": "^8.0.2",

scripts/generate.mjs

@@ -1,8 +1,13 @@
 #!/usr/bin/env -S npx ts-node
 import "jsh";
+import yaml from "js-yaml";
+
+const openApiSpecFileName = "open_api_spec.yaml";
 
 echo("Downloading latest YNAB API OpenAPI spec...");
-exec(`wget https://api.ynab.com/papi/open_api_spec.yaml -O open_api_spec.yaml`);
+exec(
+  `wget https://api.ynab.com/papi/${openApiSpecFileName} -O ${openApiSpecFileName}`
+);
 
 echo("Running openapi-generator generate...");
 const generatorConfigOptions = `modelPropertyNaming=original,useSingleRequestParameter=false`;
@@ -14,4 +19,10 @@ echo('Removing `Null: "null"` from enum definitions...');
 // The generator does not provide a way to disable this behavior, so we will remove these items manually.
 exec(`find ./src/models -type f -exec sed -i '' "s/Null: 'null'//g" {} +`);
 
+const openApiSpec = yaml.load(readFile(openApiSpecFileName));
+const serverSpecVersion = openApiSpec.info.version;
+const packageFile = JSON.parse(readFile("./package.json"));
+packageFile.description = `Official JavaScript client for the YNAB API. API documentation available at https://api.ynab.com. Generated from server specification version ${serverSpecVersion}`;
+writeFile("./package.json", JSON.stringify(packageFile, null, 2));
+
 echo.green("Success!");