OpenAPI Client Generator
Vijay Nayar
madric at gmail.com
Mon Jan 2 10:08:23 UTC 2023
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](https://spec.openapis.org/oas/latest.html) 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](https://stripe.com/en-de), 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:
1. "Service" classes represent groups of related API Endpoints by
URL.
2. Each method of a "Service" class corresponds to a single API
Endpoint.
3. 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.
More information about the Digitalmars-d-announce
mailing list