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.
A better approach:
- 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 is the GitHub location: https://github.com/swagger-api/swagger-codegen
- Use a configuration file to control the naming of your folders
- Take in an input URL – you can point directly at the URL: https://content-services.dtn.com/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