Ada.README.mustache Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of openapi-generator Show documentation
There is a newer version: 7.7.0
# {{appDescription}} - OpenAPI Ada Server

## Overview

This Ada server was generated by the [OpenAPI Generator](https://openapi-generator.tech) project.
By using the [OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) from a remote server,
you can easily generate a server stub.

## Alire setup

Use [Alire](https://github.com/alire-project/alire) to setup and build the project.
First, import the [OpenAPI Ada](https://gitlab.com/stcarrez/openapi-ada) server library with:

```shell
alr with openapi_server
```

Then choose a servlet web container that will handle the requests.
Two web server implementations are provided:

* [AWS](https://github.com/AdaCore/aws)
* [EWS](https://github.com/simonjwright/ews)

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

```
alr with servletada_aws
alr with servletada_ews
```

Once these steps are made, build the project with

```
alr build
```

After the build is successful, you will get the server binary
in `bin/{{packageName}}_aws` or `bin/{{packageName}}_ews` and you can start it as follows:

```shell
  ./bin/{{packageName}}_aws
```

## Structure of the server

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

Source file | Package | Description
------------ | ------------- | -------------
src/{{packageName}}.ads|{{package}}|The server root package declaration
src/{{packageName}}-servers.ads|{{package}}.Servers|The server declaration and instantiation
src/{{packageName}}-servers.adb|{{package}}.Servers|The server implementation (empty stubs)
src/server/{{packageName}}-skeletons.ads|{{package}}.Skeletons|The server skeleton declaration
src/server/{{packageName}}-skeletons.adb|{{package}}.Skeletons|The server skeleton implementation
src/server/{{packageName}}-models.ads|{{package}}.Skeletons|The server model types declaration
src/server/{{packageName}}-models.adb|{{package}}.Skeletons|The server model types implementation
src/{{packageName}}-server.adb|{{package}}.Server|The server main procedure
src/aws/{{packageName}}_aws.adb||The Ada Web Server server main procedure
src/ews/{{packageName}}_ews.adb||The Embedded Web Server server main procedure

Files generated in **src/server** should not be modified.  The server implementation
files (**src/{{packageName}}-server.ads** and **src/{{packageName}}-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 **{{package}}.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 **{{package}}.Skeletons.Skeleton** package or the **{{package}}.Skeletons.Shared_Instance**
package.  Such instantiation is done in **src/{{packageName}}-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/{{packageName}}-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 *{{basePath}}*

Method | HTTP request | Description
------------- | ------------- | -------------
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}[**{{nickname}}**]({{apiDocPath}}{{classname}}.md#{{nickname}}) | **{{httpMethod}}** {{path}} | {{summary}}
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}

### Models

{{#models}}{{#model}} - [{{package}}.Models.{{classname}}]({{modelDocPath}}{{classname}}.md)
{{/model}}{{/models}}

### Authorization

{{^authMethods}} All endpoints do not require authorization.
{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
{{#authMethods}}## {{{name}}}

{{#isApiKey}}

- **Type**: API key
- **API key parameter name**: {{{keyParamName}}}
- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
{{/isApiKey}}
{{#isBasicBasic}}

- **Type**: HTTP basic authentication
{{/isBasicBasic}}
{{#isBasicBearer}}

- **Type**: HTTP Bearer Token authentication{{#bearerFormat}} ({{{.}}}){{/bearerFormat}}
{{/isBasicBearer}}
{{#isHttpSignature}}

- **Type**: HTTP signature authentication
{{/isHttpSignature}}
{{#isOAuth}}

- **Type**: OAuth
- **Flow**: {{{flow}}}
- **Authorization URL**: {{{authorizationUrl}}}
- **Scopes**: {{^scopes}}N/A{{/scopes}}
{{#scopes}}  - **{{{scope}}}**: {{{description}}}
{{/scopes}}
{{/isOAuth}}

{{/authMethods}}