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 pane 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 pane 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.

A better approach is to:

• 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.
  • 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://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.