Ada.README.mustache Maven / Gradle / Ivy
# {{appDescription}} - Swagger 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.
## Building
To build the server you will need the GNAT Ada compiler as well as
the [Swagger Ada library](https://github.com/stcarrez/swagger-ada).
When the GNAT Ada compiler and Swagger Ada libraries are installed,
run the following command:
```shell
gprbuild -p -P{{projectName}}
```
After the build is successful, you will get the server binary
in bin/{{packageName}}-server and you can start it as follows:
```shell
./bin/{{packageName}}-server
```
## 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
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}}
{{#isBasic}}
- **Type**: HTTP basic authentication
{{/isBasic}}
{{#isOAuth}}
- **Type**: OAuth
- **Flow**: {{{flow}}}
- **Authorization URL**: {{{authorizationUrl}}}
- **Scopes**: {{^scopes}}N/A{{/scopes}}
{{#scopes}} - **{{{scope}}}**: {{{description}}}
{{/scopes}}
{{/isOAuth}}
{{/authMethods}}