Menu
DTN logo Content Services

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:

{
"lang": "java",
"apiPackage": "com.mycompany.apigee.api",
"modelPackage": "com.mycompany.apigee.model",
"invokerPackage": "com.mycompany.apigee.client"
}
  • 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