Using a Swagger Spec for Code Generation

Each of the API pages shows a link to the raw JSON Swagger Specification 2.0.

The Swagger Specification is used to generate the visual documentation you can view and test out – if you have an api key.

You can also use the Swagger Specification to help you get a jump start on building a client to consume the API.

An easy approach is to:

Copy the URL and paste it into a browser.
Your browser will likely pretty-print it, so right click and go to View page source.
Select and copy the JSON.
Go to https://editor.swagger.io.
Select and delete the sample in the left pain and then paste the copied JSON Specification.
You will be prompted to convert to YAML – you choose whatever you are more comfortable reading – Okay for YAML or Cancel for JSON.
You will notice that the right pain is the same documentation as what is on our API documentation.
You can now select to generate a client side library.
- Click on the Generate Client menu option.
- A selection of over 50 different languages will appear.
- Select your language of choice.
- This will download a zip file containing a library that will help you get started consuming the API.
  - The library has initialization of target URL and authentication.
  - It has objects and methods for making the API calls.
  - It contains the response objects expected.
- You can drop the library into your existing application and easily consume the API.

That was the easy way, but not the best way because:

It uses a default naming convention for your folder structures or packages it uses in constructing the library. If you do this for multiple Swagger Specifications, you would have naming collisions.
There are a lot of manual steps – fine for a quick and easy first time, but not ideal for ongoing handling of updates and changes.

Download the Swagger Command Line Code generator from here: https://swagger.io/tools/swagger-codegen/ or from GitHub here: https://github.com/swagger-api/swagger-codegen.
This is a Java based code generation library, so if you don’t have Java on your system, you will need to install that too.
The command line tool can:
- Reference a location for the Swagger Specification on GitHub: https://github.com/swagger-api/swagger-codegen.
- Use a configuration file to control the naming of your folders.
```
{
  "lang": "java",
  "apiPackage": "com.mycompany.apigee.api",
  "modelPackage": "com.mycompany.apigee.model",
  "invokerPackage": "com.mycompany.apigee.client"
}
```
- Take in an input URL – you can point directly at the URL: https://cp-docs.dtn.com/content-packages/api-specs/weather-api/weather-api-1.0.json as an example.
- Define the output folder to write the generated code.
- Automatically generates some test stubs.
This approach allows for your client to easily handle any updates or changes to the API.
You can make this part of your client build process.
You could build it quickly in multiple languages.