Home

Awesome

OpenAPI Ada Library

Alire Alire Build Status Test Status Coverage License GitLab Commits

OpenAPI Generator is a code generator that supports generation of API client libraries, server stubs and documentation automatically given an OpenAPI Spec.

The Ada client and server support has been integrated in OpenAPI Generator.

The OpenAPI Ada library is a small support library for the Ada code generator provided by OpenAPI Generator. The library provides support to serialize the data, make HTTP requests and support the OpenAPI Spec specific operations or types.

Version 0.9.0 - Under development

Version 0.8.0 - Sep 2024

List all versions

Using with Alire

If you are using Alire in your project, run the following command within your Alire project to use the library:

OpenAPI Client

alr with openapi

For the HTTP connection, you can either use AWS or Curl and run one of the following commands:

alr with utilada_curl
alr with utilada_aws

OpenAPI Server

alr with openapi_server

For the server part, you must choose a servlet web container that will handle the requests. Two web server implementations are provided:

and you should run one of the following alr command depending on your choice:

alr with servletada_aws
alr with servletada_ews

Using without Alire

If you don't have Alire or want to build and install the library on a specific place, run a setup command to configure the build as well as installation directory.

The OpenAPI Ada library provides support for client and server. The client part has less constraints than the server part which needs more components.

The HAVE_ALIRE configuration allows you to disable the build with Alire, the HAVE_SERVER controls whether you want to build and get the support for the server part, the HAVE_AWS controls the support for AWS, HAVE_CURL the support for Curl in the client part and HAVE_EWS controls the support for EWS as server.

make setup BUILD=debug PREFIX=/build/install HAVE_ALIRE=no HAVE_EWS=no HAVE_AWS=yes \
    HAVE_SERVER=yes HAVE_CURL=no

Since this build method does not verify that all dependencies are met, make sure that you have already built and install the following components and they are available to gprbuild through ADA_PROJECT_PATH if needed:

The server part needs the following components:

Then build, run the unit tests and install by using:

make
make test
make install

To use the installed libraries, make sure your ADA_PROJECT_PATH contains the directory where you installed the libraries (configured by the PREFIX=<path> option in the setup phase). The installed GNAT projects are the same as those used when using Alire.

The git repository comes with a pre-compiled OpenAPI Generator that will be installed in /usr/local/share/openapi-ada/openapi-generator-cli.jar. To help in launching the generator, a script is installed in /usr/local/bin/openapi-generator. You must have a Java JRE installed to be able to run the generator.

Docker

A docker container is available for those who want to try OpenAPI Ada without installing and building all required packages. To use the OpenAPI Ada docker container you can run the following commands:

sudo docker pull ciceron/openapi-ada

Using OpenAPI Ada

Generating the REST client from OpenAPI Spec

The command to generate an Ada REST client is the following:

  alr exec -- openapi-generate-client -i my-api.yaml \
       --additional-properties projectName=MyProject \
       --additional-properties openApiName=OpenAPI \
       --additional-properties httpSupport=Curl \
       --model-package MyProject.MyModule -o .

where my-api.yaml is the OpenAPI specification file that describes your API, MyProject is the name of the GNAT project to use, MyProject.MyModule is the name of the Ada package that will be the parent package of the generated Ada packages.

The generator will create several files in client/src/client with basically two packages: MyProject.MyModule.Models and MyProject.MyModule.Clients. The Models child package will contain the type definitions for the API operations describes in the YAML file and the Clients child package will contain the Client_Type tagged record with the API operations to invoke the REST API.

For example, if the YAML description file contains the following API operation:

openapi: 3.0.0
servers:
  - url: 'https://todo.vacs.fr/v1'
  - url: 'http://todo.vacs.fr/v1'
info:
  title: Todo API
  description: Todo API
  version: 1.0.0
  termsOfService: 'https://todo.vacs.fr/terms/'
  contact:
    email: Stephane.Carrez@gmail.com
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
  - name: tasks
    description: Tasks
paths:
  /:
    get:
      tags:
        - tasks
      summary: Redirect to the UI
      description: |
        Default operation to redirect to the UI index page.
      operationId: redirectTodos
      responses:
        '302':
          description: redirect to the UI page
  /todos:
    get:
      tags:
        - tasks
      summary: List the available tasks
      description: |
        The list of tasks can be filtered by their status.
      operationId: listTodos
      parameters:
        - name: status
          in: query
          description: Filters the tasks by their status
          required: false
          schema:
            type: string
            enum:
              - done
              - waiting
              - working
              - all
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Todo'
        '400':
          description: Invalid status value
      security:
        - todo_auth:
            - 'read:todo'
security:
  - todo_auth: []
externalDocs:
  description: Find out more about Swagger
  url: 'http://swagger.io'
components:
  securitySchemes:
    todo_auth:
      type: oauth2
      flows:
        password:
          tokenUrl: 'http://localhost:8080/v1/oauth/token'
          scopes:
            'write:todo': Write a todo
            'read:todo': Read a todo
  schemas:
    Todo:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: The todo identifier
        title:
          type: string
          description: The todo title
        create_date:
          type: string
          format: date-time
          description: The todo creation date
        done_date:
          type: string
          format: date-time
          description: The todo resolution date
        status:
          type: string
          description: The todo state
          enum:
            - waiting
            - working
            - done
      required:
        - id
        - title
        - status
        - create_date
      example:
        id: 23
        title: Make the FOSDEM presentation
        description: password
        status: working
        create_date: '2017-12-24T00:00:00.000Z'
      xml:
        name: Todo

The generator will generate the following Ada code in the Models child package:

package Todos.Models is
   ...
   type Todo_Type is
     record
       Id : OpenAPI.Long;
       Title : OpenAPI.UString;
       Create_Date : OpenAPI.Datetime;
       Done_Date : OpenAPI.Nullable_Date;
       Status : OpenAPI.UString;
     end record;
     ...
end Todos.Models;

and the following code in the Clients child package:

package Todos.Clients is
   ...
   type Client_Type is new OpenAPI.Clients.Client_Type with null record;
   --  List the available tasks
   --  The list of tasks can be filtered by their status.
   procedure List_Todos
      (Client : in out Client_Type;
       Status : in OpenAPI.Nullable_UString;
       Result : out Todos.Models.Todo_Type_Vectors.Vector);

   --  Redirect to the UI
   --  Default operation to redirect to the UI index page.
   procedure Redirect_Todos
      (Client : in out Client_Type);
   ...
end Todos.Clients;

Initialization

The HTTP/REST support is provided by Ada Util and encapsulated by OpenAPI Ada. This support is either based on Curl or on AWS. The OpenAPI code generator uses Curl by default and this can be changed when running the openapi-generator tool and changing the following option:

       --additional-properties httpSupport=aws

If you want to use Curl, the initialization should use the following:

   Util.Http.Clients.Curl.Register;

But if you want to use AWS, you will initialize with:

   Util.Http.Clients.AWS.Register;

Curl may be easier to start with because AWS does not support HTTP DELETE operation except in some latest version.

After the initialization is done, you will declare a client instance to access the API operations:

   C : Todos.Clients.Client_Type;

The 'Client_Type' is the generated type that will implement the operations described in the OpenAPI description file.

And you should initialize the server base URI you want to connect to:

  C.Set_Server ("http://localhost:8080/v1");

At this stage, you can use the generated operation.

Calling an operation

Let's retrieve some todo list by calling the 'List_Todo' operation. 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:

  List     : Todos.Models.Todo_Type_Vectors.Vector;

And then call the 'Get_Pet_By_Id' operation:

  C.List_Todos ((Is_Null => True, Value => <>), List);

At this stage, you can access the list of todos:

procedure Print (Todo : in Todos.Models.Todo_Type) is
begin
   Put (OpenAPI.Long'Image (Todo.Id));
   Set_Col (6);
   Put (OpenAPI.To_String (Todo.Status));
   Set_Col (15);
   Put (Ada.Calendar.Formatting.Image (Todo.Create_Date));
   Set_Col (40);
   if Todo.Done_Date.Is_Null then
      Put ("-");
   else
      Put (Ada.Calendar.Formatting.Image (Todo.Done_Date.Value));
   end if;
   Set_Col (60);
   Put (OpenAPI.To_String (Todo.Title));
   New_Line;
end Print;

  for T of List loop
     Print (T);
  end loop;

Documentation

The OpenAPI Ada sources as well as a wiki documentation is provided on:

Examples