Writing an OpenAPI document
The OpenAPI document is either a JSON or a YAML file that describes the REST API operations. The document can be used both for the documentation of the API and for the code generation in several programming language. We will see briefly through the Petstore example how the OpenAPI document is organized. The full OpenAPI document is available in petstore.yaml.
A first part of the OpenAPI document provides a general description of the API. This includes the general description, the terms of service, the license and some contact information.
description: 'This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://s
wagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key
` to test the authorization filters.'
title: Swagger Petstore
email: [email protected]
name: Apache 2.0
The OpenAPI document can also describe types which are used by the REST operations. These types provide a description of how the data is organized and passed through the API operations.
It is possible to describe almost all possible types from simple properties, group of properties up to complex types including arrays. For example a
Pet type is made of several properties each of them having a name, a type and other information to describe how the type is serialized.
title: a Pet
description: A pet for sale in the pet store
description: pet status in the store
In this example, the
Pet type contains 6 properties (
status) and refers to two other types
Operations are introduced by the
paths object in the OpenAPI document. This section describes the possible paths that can be used by URL and the associated operation. Some operations receive their parameter within the path and this is represented by the
The operation description indicates the HTTP method that is used
The following definition describes the
summary: Find pet by ID
description: Returns a single pet
- name: petId
description: ID of pet to return
description: successful operation
description: Invalid ID supplied
description: Pet not found
- api_key: 
description are used for the documentation purposes. The
operationId is used by code generators to provide an operation name that a target programming language can use. The
produces section indicates the media types that are supported by the operation and which are generated for the response. The
parameters section represents all the operation parameters. Some parameters can be extracted from the path (which is the case for the
petId parameter) and some others can be passed as query parameter.
responses section describes the possible responses for the operation as well as the format used by the response. In this example, the operation returns an object described by the
Using Swagger Codegen
The documentation and the Ada client are generated from the OpenAPI document by using the Swagger Codegen generator. The generator is a Java program that is packaged within a jar file. It must be launched by the Java 7 or Java 8 runtime.
Generating the documentation
The HTML documentation is generated from the OpenAPI document by using the following command:
java -jar swagger-codegen-cli.jar generate -l html -i petstore.yaml -o doc
Generating the Ada client
To generate the Ada client, you will use the
-l ada option to use the Ada code generator. The OpenAPI document is passed with the
java -jar swagger-codegen-cli.jar generate -l ada -i petstore.yaml -o client \
-DprojectName=Petstore --model-package Samples.Petstore
The Ada generator uses two options to control the generation. The
-DprojectName=Petstore option allows to control the name of the generated GNAT project and the
--model-package option controls the name of the Ada package for the generated code.
The Ada generator will create the following Ada packages:
Samples.Petstore.Models is the package that contains all the types described in the OpenAPI document. Each OpenAPI type is represented by an Ada record and it
is also completed by an instantiation of the
Ada.Containers.Vectors package for the representation of arrays of the given type. The
Models package also provides
Deserialize procedures for the serialization and deserialization of the data over JSON or XML streams.
Samples.Petstore.Clients is the package that declares the
Client_Type tagged record which provides all the operations for the OpenAPI document.
Pet type describe previously, the Ada generator produces the following code extract:
package Samples.Petstore.Models is
type Pet_Type is
Id : Swagger.Long;
Category : Samples.Petstore.Models.Category_Type;
Name : Swagger.UString;
Photo_Urls : Swagger.UString_Vectors.Vector;
Tags : Samples.Petstore.Models.Tag_Type_Vectors.Vector;
Status : Swagger.UString;
and for the operation it generates the following code:
package Samples.Petstore.Clients is
type Client_Type is new Swagger.Clients.Client_Type with null record;
(Client : in out Client_Type;
Pet_Id : in Swagger.Long;
Result : out Samples.Petstore.Models.Pet_Type);
Using the REST Ada client
The HTTP/REST support is provided by Ada Util and encapsulated by Swagger Ada. The Ada Util library also takes care of the JSON and XML serialization and deserialization. If you want to use Curl, you should initialize with the following:
But if you want to use AWS, you will initialize with:
After the initialization is done, you will declare a client instance to access the API operations:
C : Samples.Petstore.Clients.Client_Type;
And you should initialize the server base URL you want to connect to. To use the live Swagger Petstore service you can set the server base URL as follows:
At this stage, you can use the generated operation by calling operations on the client.
Calling a REST operation
Let's retrieve some pet information by calling the
Get_Pet_By_Id operation described previously. This operation needs an integer as input parameter and returns a
Pet_Type object that contains all the pet information. You will first declare the pet instance as follows:
Pet : Samples.Petstore.Models.Pet_Type;
And then call the
C.Get_Pet_By_Id (768, Pet);
At this stage, you can access information from the
Ada.Text_IO.Put_Line ("Id : " & Swagger.Long'Image (Pet.Id));
Ada.Text_IO.Put_Line ("Name : " & Swagger.To_String (Pet.Name));
Ada.Text_IO.Put_Line ("Status : " & Swagger.To_String (Pet.Status));
The Swagger Ada Petstore illustrates other uses of the generated operations. It allows to list the inventory, list the pets with a given status, add a pet and so on...
Conclusion and references
The OpenAPI Specification provides a standard way to describe REST operations. The Swagger Codegen is the generator to be used to simplify the implementation of REST clients in many programming languages and to generate the documentation of the API. The Ada code generator only supports the client side but the server code generation is under work.
The sources of the petstore samples are available:
The APIs.guru lists more than 550 API descriptions from various providers such as Amazon, Google, Microsoft and many other online services. They are now available to the Ada community!