hs-remote-managers

Headspace OpenAPI Generator Repo

Generates REST client libraries based on OpenAPI-compatible specifications.

Clients are generated using the OpenAPI Generator. Whatever it supports is what we can support. If you run into issues, check the documentation for the generator before reaching out. This github repository just stores scripts to manage the different clients and provide a convention for making new clients.

Prerequisites

You will need Java and Node installed. If you're publishing to a repository, you'll need whatever tool is necessary to publish it there.

How to Generate a client

• Make sure it doesn't exist already. If it does, don't make another one.

• If the service you want to make a client for lis not listed in the configs folder, make a new folder for your service. It should just be the name of the service.

• In the folder for your service, create a file named {{generator}}.yml. This will be the config file that is passed to the OpenAPI Generator to generate your client. Each generator has its own configuration options, most of which have examples here. If you're unsure what options are available, check the link and look for your generator.

   Conventions to follow:
   - `outputDir` should be `artifacts/{{service}}/{{generator}}`
   - `npmName` should be `@headspace/openapi-{{service}}-{{generator}}-sdk`
  
   These conventions are just to make things predictable.
  

• supply a single config as an argument to the generator script, e.g. yarn build sleep-content/typescript-axios.yml to generate only that file.

• Optional run yarn build which will scan through the configs and batch generate all the artifacts.

HOW TO PUBLISH

• navigate into the newly created directory artifacts/{service}/{generator}/ and run npm install
• before you "npm publish" you will need to "npm login" or "npm adduser"
• If this exists in your generated package.json, you may need to remove it to successfully publish:

"publishConfig": {
    "registry": "https://npmjs.com/registry"
}

• Run yarn publish --otp={npm code from authenticator app}

What to commit into this github repository

• any new configs you made
• source code for the artifacts you made

For the most part, just commit everything.

Publishing your client

THIS IS A MANUAL PROCESS. YOU ARE RESPONSIBLE FOR PUBLISHING. CIRCLE_CI WILL NOT DO ANYTHING FOR YOU.

• Navigate to your created artifacts in the artifacts folder.
• Open the README file.
• Read the README.

Issues

• Contentful and some of Headspace services use a locale of the form {languageCode}-{regionCode} e.g. en-US. As a result, we can see the locale in the field names of a request payload and response. Unfortunately, Open API Generator doesn't support hyphen in the field names, it transforms en-US to en_US. We need to replace en_US to en-US back once a service SDK is generated to avoid the contract mismatching.