Creating an OpenAPI Specification for Gen™ REST calls
In this article we will show you how to create an OpenAPI specification in order to configure a Call REST statement for your Gen applications.
In order to construct a REST call, Gen needs a variety of information:
● Where to find the service (the URL)
● How to add parameters to the call
● What the body of the response will look like
● How to build a request
Developers can easily input this information by using an OpenAPI specification, an open source file that specifies the endpoints, parameters, and authentication methods for a RESTful API. However, not all services provide an Open API specification. Fortunately, these specifications can be written in YAML or JSON, which are easily human-readable so you can create your own.
Boxed Solutions
There are a number of tools available for generating OpenAPI specifications, including:
● Swagger’s Visual Editor
● Open API Tools Editor
● Stoplight Studio
However, these tools require purchase and are more aimed at generating the specification from the API code, rather than from the JSON request and response messages.
DIY — Do It Yourself
If you don’t have access to the boxed solutions or aren’t getting the results you need, writing the specification by hand may be your best option. To guide you through this process, we’ll use this simple public REST API, “Dog API” http://dog-api.kinduff.com.
Sample — YAML — “Dog API”
- Create the header. This enables Gen to recognize the file as an OpenAPI specification. The header information is a boilerplate and looks like:
openapi: 3.0.0
info:
contact:
name: kinduff
url: https://kinduff.github.io/dog-api/
description: “Dog API provides dog facts as a service.”
title: Dog API
version: 1.0
● The openapi tag identifies this as using the version 3 specification.
● The info tag identifies optional information about the API. Gen does not use this tag, but the information is helpful for identifying the file on your system. If this tag is used, all of the information shown (contact, description, title, and version) must be present.
2. Identify the server(s) for the API. If this is not entered, Gen will require a URL either in the REST properties file or as a runtime configuration parameter. The server information looks like:
servers:
- url: http://dog-api.kinduff.com
3. Define the actual API. In OpenAPI terminology, an API call is a path, so the section is called paths, and the initial information looks like:
paths:
/api/facts:
get:
description: Retrieve a number of random facts about dogs
4. Define the parameters. Parameters may appear as part of the URL or as part of the header. This “Dog API” has a query parameter called ‘number’, which represents the number of dog facts to return. From the API documentation, we know that this is an optional parameter. The parameter description looks like:
parameters:
- description: Number of facts
name: number
in: query
required: false
schema:
type: integer
format: int32
● The fields used to describe the parameter are pretty self-explanatory. The “in” property identifies where the parameter will appear in the request; the “required” property indicates whether the parameter must appear in the request; and “schema” identifies the data type and optional format. In this case, the parameter named “number” appears in the query, is not required, and is a 32-bit integer.
5. Send a sample request. Use a tool like Postman to send a sample request and get the response information as shown below:
Image 1: Send sample query with Postman
As image 1 shows, this API returns an array of strings and a Boolean status.
6. Define the responses. The responses contain information similar to the parameters:
responses:
“200”:
description: Successful response
content:
application/json:
schema:
type: object
properties:
facts:
type: array
items:
type: string
success:
type: boolean
“404”:
description: Cannot find the API
● In this case, the specification gives a lot of information about the response. It shows that the API can either return a successful response (200) or a not found response (404). The example also shows that the API returns a JSON object that contains an array of strings called facts and a Boolean value called success. Both of these are illustrated in the screenshot of the Postman session.
The final version of the specification looks like:
openapi: 3.0.0
info:
contact:
name: kinduff
url: https://kinduff.github.io/dog-api/
description: “Dog API provides dog facts as a service.”
title: Dog API
version: 1.0
servers:
- url: http://dog-api.kinduff.com
paths:
/api/facts:
get:
description: Retrieve a number of random facts about dogs
parameters:
- description: Number of facts
name: number
in: query
required: false
schema:
type: integer
format: int32
responses:
“200”:
description: Successful response
content:
application/json:
schema:
type: object
properties:
facts:
type: array
items:
type: string
success:
type: boolean
“404”:
description: Cannot find the API
Conclusion
While the idea of manually creating an OpenAPI specification may seem daunting, this example shows that a specification can be created easily for any REST service that does not provide one. With your OpenAPI specification you can configure the Call REST statement for your Gen applications.
For more information about configuring your Gen applications to consume REST APIs, follow this Gen EDGE Community announcement. The Gen EDGE Community is where the Gen team posts all of the latest news about Gen, including new enhancements, roadmap and certification plans, training webcasts, etc. Join the Gen EDGE community to get automated notifications and always stay informed.
Additional Useful Information
Creating OpenAPI Specification (OAS) by Hand
OpenAPI Spec Caveat for Gen
