OpenAPI Client Generator

January 02, 2023

Posted by Vijay Nayar

Permalink

Vijay Nayar

Permalink

I would like to put an announcement for two new projects added to https://code.dlang.org.

https://code.dlang.org/packages/openapi-client

This project is an executable that reads an OpenAPI Specification in JSON format and writes a D client to interact with the described REST API.

https://code.dlang.org/packages/stripe-client

This project contains code produced by the openapi-client project to provide an interface to Stripe, which is a service that allows one to make and receive online payments using a wide variety of methods, ranging from Credit Cards, to bank transfers, to even invoices.

Usage of the client libraries generated by openapi-client follows a similar pattern:

"Service" classes represent groups of related API Endpoints by URL.
Each method of a "Service" class corresponds to a single API Endpoint.
The methods generally take up to 3 arguments:
- Parameters: These ultimately translate into path, header, cookie, or query-string parameters of the endpoint, depending on the OpenAPI Specification.
- RequestBody: This corresponds to the uploaded HTTP request body for POST or PUT requests.
- ResponseHandler: A object to set typed delegates to handle endpoint responses. The types may vary depending on the status code, e.g. a 200 OK might process a ChargeList argument, but a 400 NOT FOUND response might provide an Error_ argument instead.

Example code:

import stripe.security : Security;
import stripe.service.v1_charges_service : V1ChargesService;
import vibe.data.json : serializeToJsonString;

// 1. Stripe's OpenAPI specification has two valid security schemes:
//   - HTTP Basic Auth (named "BasicAuth")
//   - HTTP Bearer Auth (named "BearerAuth")
Security.configureBasicAuth(
    "sk_test_51MFbD...vri",  // Username / API key
    "");                     // With Stripe, the password is always blank.

// 2. Service classes are created from valid URL paths + "Service", e.g. "/v1/charges" => "V1ChargesService".
auto service = new V1ChargesService();

// 3. Each endpoint has a "Params" object which covers any path, query-string, header, or cookie parameters.
auto params = new V1ChargesService.GetChargesParams();

// 4. Some requests have a request body, which will be an argument to the method,
// e.g. "postCharges(params, requestBody, handler)".

// 5. Different HTTP status codes can be associated with different data types.
// Create a handler object and add your own delegates that say what to do with each response.
auto handler = new V1ChargesService.GetChargesResponseHandler();

// 6. This handler is for a successful 200 response, there's also a default handler for errors.
handler.handleResponse200 = (V1ChargesService.GetChargesResponseHandler.ChargeList chargeList) {
  // Simply print out our response in JSON format.
  writeln(serializeToJsonString(chargeList));
};

// 7. Now call the desired endpoint and your handler will be invoked depending on the response.
service.getCharges(params, handler);

Feedback is always welcome, or bugs can be reported on each project's GitHub Issues.

Forums