Helper to create a dynamic Ruby OpenAPI/Swagger client to a REST API

Question

I used Bravado to create a Python client to a REST API for the petstore.

I need to do the same to get a dynamic Ruby client to the REST API.

• I saw a list of tools in the OS integrations Swagger page but most of them seems to be to automate tests using Swagger or to create a Swagger/openapi API, not to create Client that consume a Swagger API.

• Svelte, is a "Dynamic Ruby API Client from Swagger JSON Spec" in the above list. It could be a good candidate, and looks similar to the Bravado Python lib I already use, but:

  • it seems that Request parameter validation is only done for URL-based parameters, so it will not provide requests, and the responses validation against the Swagger 2.0 Spec like here.
  • Svelte returns a Faraday::Request not a model instance.
• Ruby gem OpenAPI is officially a Ruby wrapper, which is what we are looking for, but there is not yet any documentation Cf. the main README: "In Active dev. documentation is coming"
• Excon (thank you @kevin-burnett to point at it) does not provide an automated wrapper to the API describe by Swagger, it's an HTTP client, corresponding to Python's Requests, so a lib to manually consume the API.

Here is code in Python that is the kind of feature we are looking for in Ruby:

To get simple dict answer (without using models):

from bravado.client import SwaggerClient
from bravado.fido_client import FidoClient

client = SwaggerClient.from_url(
    'http://petstore.swagger.io/v2/swagger.json',
    config={'use_models': False}
)

result = client.pet.getPetById(petId=42).result(timeout=4)

provide:

>>> result
{'category': {'id': 42, 'name': 'string'},
 'id': 42,
 'name': 'doggie',
 'photoUrls': ['string', 'string2'],
 'status': 'available',
 'tags': [{'id': 42, 'name': 'string'}]}

And even better, by default using the model:

> from bravado.client import SwaggerClient

> client = SwaggerClient.from_url("http://petstore.swagger.io/v2/swagger.json")
> pet = client.pet.getPetById(petId=42).result()
> print(pet)
Pet(category=Category(id=42, name='string'), id=42,
    name='doggie', photoUrls=['string', 'string2'],
    status='available',
    tags=[Tag(id=42, name='string')])
>

Answer 1

You can use ruby-swagger to convert swagger.json to API client

You can look at this command:

 rake swagger:generate_client:ruby

Also you can look at swagger-codegen

Answer 2

There are lots of others, but excon is pretty sweet.

Include it in your Gemfile:

gem 'excon'

Then, to to do a GET request, for example:

require 'json'
require 'excon'
excon_result = Excon.get('http://petstore.swagger.io/v2/pet/findByStatus?status=pending')
response_body_as_string = excon_result.body
pets = JSON.parse(response_body_as_string)
pets.first['name'] # "hello kity with form updated" (sic)

Excon has lots of neat features such as the expects option that allows you to specify a list of http status codes that you expect. If the response is outside of the expectation, it will raise automatically.