API Code Generation with Swagger

Alex Egg,

Understandably so, the prevailing theme among developers in the ruby/rails community is against the enterprise. One of the hallmarks of enterprise development is SOAP web services and XML configs. However, I think some of these technologies have a place in the ruby/rails world. One I have discovered recently in working a/ an enterprise team is WSDL/WADL which are documents that describe a web service. To understand, consider some context: Today if I had a job to interface w/ a REST web service I would code up the client in ruby using HTTParty, it’s a lot of boilerplate code and would take most of the day to write and test. Then if the server API changes I need to update my client too – an inconvenience. When we need to interface with a REST API we usually code the client by had, or if we are lucky we can use some type of dynamic tool like ActiveResource if our API is strictly compliant. My points is that our clients are very brittle. This problem has been tackled in a few ways by tools like WSDL/WADL.

When you create your API you attribute you code so that you generate an intermediary description file, usually XML. The description document describes all your endpoints, the parameters they take and the return types. Using this document you can generate the code for your client. SO when the API method parameters change, I don’t have to update my client, I just generate a new one. WADL has many code generators. This notion of API code generation is on absent from the REST world. A fresh approach at it is undertaken by the Swagger project.

Using plugins for your environment, rails, for example, I can annotate my controller with a few basic details and then it can infer the rest of the details about the API. From there it outputs a JSON description document which describes in a structured way HOW to interface my api. The swagger project also comes with a handfull of useful generators too. For example recently I had to make an API for an ios project. I didn’t want to have to type all the code for my IOS API client, so I experimented w/ swagger. I was able to generate the client for all my API in objective C code. Also, it has generators of android and many other platforms. This generated code works perfectly out of the box and allows me to stay up-to-date with the API more easily and focus on the core value of my app, not the network layer.

Here’s an example of my swagger annotated rails controller:

class Api::V1::CardsController < ApiController
  before_action :set_card, only: [:show, :edit, :update, :destroy]

  swagger_controller :cards, "Cards"
  
  swagger_api :index do
     summary "Fetches all cards"
     notes "You may want to use /users/:id/cards to scope by user -- get all user's cards"
     response :unauthorized
     response :not_acceptable
   end
   
   swagger_api :show do
       summary "Fetches a single Card item"
       notes "This is usually done after the client receives a push request (card broadcast from another user)"
       param :path, :id, :integer, :optional, "Card Id"
       response :unauthorized
       response :not_acceptable
       response :not_found
     end
     
     swagger_api :create do
         summary "Creates a new Card"
         param :body, :user, :user, :required, "A User JSON object"
         response :unauthorized
         response :not_acceptable
       end
      
      swagger_api :update do
         summary "Updates an existing Card"
         param :path, :id, :integer, :required, "User Id"
         param :form, :first, :string, :required, "First name"
         param :form, :last, :string, :required, "Last name "
         param :form, :status_message, :string, :required, "Status Message"
         response :unauthorized
         response :not_found
         response :not_acceptable
       end
       
       swagger_api :destroy do
         summary "Deletes an existing Card item"
         param :path, :id, :integer, :optional, "Card Id"
         response :unauthorized
         response :not_found
       end
       
       swagger_api :queue do
           summary "Queues a card for geo-broadcast"
           notes "Use this endpoint to broadcast this card to the geo-proximity"
           param :path, :id, :integer, :optional, "Card Id"
           response :unauthorized
           response :not_acceptable
         end
         
         swagger_model :card do
           description "A Card object."
           property :id, :integer, :required, "User Id"
           property :first, :string, :required, "First name"
           property :last, :string, :required, "Last name"
           property :status_message, :string, :required, "Status Message"
         end
....
....
....

Swagger also has a code generator that creates an HTML site that you can use to test your API. The website acts as the client and hits your APIS via AJAX requests.

asdf


Permalink: api-code-generation-w-swagger

Tags:

Last edited by Alex Egg, 2016-10-05 19:10:03
View Revision History