Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stcarrez/swagger-ada-todo
Simple todo list server with OpenAPI
https://github.com/stcarrez/swagger-ada-todo
ada examples openapi
Last synced: about 2 months ago
JSON representation
Simple todo list server with OpenAPI
- Host: GitHub
- URL: https://github.com/stcarrez/swagger-ada-todo
- Owner: stcarrez
- Created: 2018-02-01T21:20:44.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-09-12T21:22:16.000Z (4 months ago)
- Last Synced: 2024-09-13T11:00:33.959Z (4 months ago)
- Topics: ada, examples, openapi
- Language: Ada
- Homepage:
- Size: 41.7 MB
- Stars: 8
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Todo API - OpenAPI Ada Server
## Overview
This Ada client and server was generated by the [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) project.
By using the [OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) 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](https://github.com/stcarrez/swagger-ada).
When the GNAT Ada compiler and OpenAPI Ada libraries are installed,
run the following command:
```sh
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:
```sh
./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](https://github.com/stcarrez/swagger-ada).
Then, restart the server.
## Structure of the server
The server consists of several Ada packages that are generated from
the OpenAPI specification.
Source file | Package | Description
------------ | ------------- | -------------
src/todos.ads|Todos|The server root package declaration
src/todos-servers.ads|Todos.Servers|The server declaration and instantiation
src/todos-servers.adb|Todos.Servers|The server implementation (empty stubs)
src/server/todos-skeletons.ads|Todos.Skeletons|The server skeleton declaration
src/server/todos-skeletons.adb|Todos.Skeletons|The server skeleton implementation
src/server/todos-models.ads|Todos.Skeletons|The server model types declaration
src/server/todos-models.adb|Todos.Skeletons|The server model types implementation
src/todos-server.adb|Todos.Server|The server main procedure
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*
Method | HTTP request | Description
------------- | ------------- | -------------
[**Create_Todo**](TasksApi.md#Create_Todo) | **POST** /todos | Create a todo
[**Delete_Todo**](TasksApi.md#Delete_Todo) | **DELETE** /todos/{todoId} | Delete the todo
[**List_Todos**](TasksApi.md#List_Todos) | **GET** /todos | List the available tasks
[**Update_Todo**](TasksApi.md#Update_Todo) | **PUT** /todos/{todoId} | Update the todo
## Models
- [Todos.Models.Todo_Type](Todo_Type.md)
## 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 .
```