openapi

Developer-friendly & type-safe Ruby SDK specifically catered to leverage openapi API.

Important

This SDK is not yet ready for production use. To complete setup please follow the steps outlined in your workspace. Delete this section before > publishing to a package manager.

Summary

Swagger Petstore: This is a sample server Petstore server. You can find out more about Swagger at http://swagger.io or on irc.freenode.net, #swagger. For this sample, you can use the api key special-key to test the authorization filters.

For more information about the API: Find out more about Swagger

Table of Contents

• openapi
  • SDK Installation
  • SDK Example Usage
  • Authentication
  • Available Resources and Operations
  • Error Handling
  • Server Selection
• Development
  • Maturity
  • Contributions

SDK Installation

The SDK can be installed using RubyGems:

gem install specific_install
gem specific_install  

SDK Example Usage

Example

require 'openapi'

Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::Openapi.new(
      petstore_auth: '<YOUR_PETSTORE_AUTH_HERE>',
    )

req = Models::Components::PetInput.new(
  name: 'doggie',
  photo_urls: [
    'https://example.com/photo.png',
  ],
)

res = s.pet.add_pet(request: req)

if res.status_code == 200
  # handle response
end

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

Name	Type	Scheme
petstore_auth	oauth2	OAuth2 token

To authenticate with the API the petstore_auth parameter must be set when initializing the SDK client instance. For example:

require 'openapi'

Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::Openapi.new(
      petstore_auth: '<YOUR_PETSTORE_AUTH_HERE>',
    )

req = Models::Components::PetInput.new(
  name: 'doggie',
  photo_urls: [
    'https://example.com/photo.png',
  ],
)

res = s.pet.add_pet(request: req)

if res.status_code == 200
  # handle response
end

Per-Operation Security Schemes

Some operations in this SDK require the security scheme to be specified at the request level. For example:

require 'openapi'

Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::Openapi.new

res = s.pet.get_pet_by_id(security: Models::Operations::GetPetByIdSecurity.new(
    api_key: '<YOUR_API_KEY_HERE>',
  ), pet_id: 311_674)

unless res.body.nil?
  # handle response
end

Available Resources and Operations

Available methods

pet

• add_pet - Add a new pet to the store
• add_pet_raw - Add a new pet to the store
• update_pet - Update an existing pet
• update_pet_raw - Update an existing pet
• find_pets_by_status - Finds Pets by status
• find_pets_by_tags - Finds Pets by tags ⚠️ Deprecated
• get_pet_by_id - Find pet by ID
• update_pet_with_form - Updates a pet in the store with form data
• delete_pet - Deletes a pet
• upload_file - Uploads an image

store

• get_inventory - Returns pet inventories by status
• place_order - Place an order for a pet
• get_order_by_id - Find purchase order by ID
• delete_order - Delete purchase order by ID

user

• create_user - Create user
• create_users_with_array_input - Creates list of users with given input array
• create_users_with_list_input - Creates list of users with given input array
• login_user - Logs user into the system
• logout_user - Logs out current logged in user session
• get_user_by_name - Get user by user name
• update_user - Updated user
• delete_user - Delete user

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or raise an error.

By default an API error will raise a Errors::APIError, which has the following properties:

Property	Type	Description
message	string	The error message
status_code	int	The HTTP status code
raw_response	Faraday::Response	The raw HTTP response
body	string	The response content

When custom error responses are specified for an operation, the SDK may also throw their associated exception. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the add_pet method throws the following exceptions:

Error Type	Status Code	Content Type
Errors::APIError	4XX, 5XX	*/*

Example

require 'openapi'

Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::Openapi.new(
      petstore_auth: '<YOUR_PETSTORE_AUTH_HERE>',
    )

begin
    req = Models::Components::PetInput.new(
      name: 'doggie',
      photo_urls: [
        'https://example.com/photo.png',
      ],
    )

    res = s.pet.add_pet(request: req)

    if res.status_code == 200
      # handle response
    end
rescue Errors::APIError => e
  # handle default exception
  raise e
end

Server Selection

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the server_url (String) optional parameter when initializing the SDK client instance. For example:

require 'openapi'

Models = ::OpenApiSDK::Models
s = ::OpenApiSDK::Openapi.new(
      server_url: 'http://petstore.swagger.io/v2',
      petstore_auth: '<YOUR_PETSTORE_AUTH_HERE>',
    )

req = Models::Components::PetInput.new(
  name: 'doggie',
  photo_urls: [
    'https://example.com/photo.png',
  ],
)

res = s.pet.add_pet(request: req)

if res.status_code == 200
  # handle response
end

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

SDK Created by Speakeasy