Awesome

Todo API - OpenAPI Ada Server

Overview

This Ada client and server was generated by the OpenAPI Generator project. By using the OpenAPI-Spec from a remote server, you can easily generate a server stub.

Building

To build the server you will need the GNAT Ada compiler as well as the OpenAPI Ada library.

When the GNAT Ada compiler and OpenAPI Ada libraries are installed, run the following command:

gprbuild -p -Ptodos

Running

After the build is successfull, you will get the server binary in bin/todos-server and you can start it as follows:

./bin/todos-server

The client example is also available in bin/todos-client and you can use it to populate the server with todos, update them, list them.

You can add a todos with the following command:

./bin/todos-client add 'Explain how to use this example'
./bin/todos-client add 'Integrate OpenAPI generator 5.0.0'
./bin/todos-client add 'Update the Swagger UI'

You can list the todos with the following command:

./bin/todos-client list
 1   waiting  2020-10-24 07:51:55      -                   Explain how to use this example
 2   waiting  2020-10-24 07:52:29      -                   Integrate OpenAPI generator 5.0.0
 3   waiting  2020-10-24 07:53:30      -                   Update the Swagger UI   

You can delete a todo by using the del command and giving the todo identifier:

./bin/todos-client del 3

You can close a todo by using the close command:

./bin/todos-client close 2

And the list command will show you that the todo is done:

./bin/todos-client list
 1   waiting  2020-10-24 07:51:55      -                   Explain how to use this example
 2   done     2020-10-24 07:52:29      2020-10-24 07:53:53 Integrate OpenAPI generator 5.0.0

Swagger UI

The server is running on localhost:8080 and it can display the Swagger UI with the list of operations supported by the server. For this, point your browser to: http://localhost:8080/v1/ui/index.html

If the server replies with a 404 error, the Swagger UI is not found in the installation path, update the todos.properties file and change the swagger.dir value:

swagger.dir=web;/usr/share/swagger-ada/web/

you may have to change /usr by the installation path (prefix) you have used for the OpenAPI Ada library. Then, restart the server.

Structure of the server

The server consists of several Ada packages that are generated from the OpenAPI specification.

Files generated in src/server should not be modified. The server implementation files (src/todos-server.ads and src/todos-server.adb) should be modified to implement the server operations. You can also customize the server main procedure according to your needs.

Server model

The server instance is represented by the Todos.Servers.Server_Type Ada type. The REST API will need an instance of it to make the operation call. Two server model exists:

• The instance per request model creates an instance of the server type for each request.
• The shared instance model shares the same instance across all concurrent REST requests. This instance is protected using an Ada protected object which holds the server instance.

The choice of the server model is made at the compilation time by instantiating either the Todos.Skeletons.Skeleton package or the Todos.Skeletons.Shared_Instance package. Such instantiation is done in src/todos-server.ads and the default is to use the Shared_Instance.

Implementing a server operation

All you have to do is implement the server operation in the src/todos-servers.adb file. The package already contains the operation with its parameters and you only have to replace the null instruction by real code.

Documentation

API Documentation

All URIs are relative to https://todo.vacs.fr/v1

Models

• Todos.Models.Todo_Type

Authorization

todoAuth

• Type: OAuth
• Flow: password
• Authorization URL:
• Scopes:
  • write:todo: Write a todo
  • read:todo: Read a todo

Docker

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

   sudo docker pull ciceron/openapi-todo
   sudo docker run --name openapi-todo -p 8080:8080 ciceron/openapi-todo

To acces the OpenAPI UI, you can point your browser to http://localhost:8080/v1/ui/index.html

To run the client, you can start in another terminal the following command:

   sudo docker exec -it openapi-todo /bin/bash

This will start a shell in the container and you can run the following commands to send REST requests on the running server:

   ./bin/todos-client add 'Explain how to use this example'
   ./bin/todos-client add 'Integrate OpenAPI generator 5.0.0'
   ./bin/todos-client add 'Update the Swagger UI'
   ./bin/todos-client list

To stop the running application you will use:

   sudo docker stop openapi-ada
   sudo docker rm openapi-ada

If you want to build locally the docker image, you can use:

   sudo docker build -t openapi-ada -f docker/Dockerfile .