{"id":13409196,"url":"https://github.com/stcarrez/swagger-ada","last_synced_at":"2025-06-12T18:34:00.533Z","repository":{"id":25003355,"uuid":"102961493","full_name":"stcarrez/swagger-ada","owner":"stcarrez","description":"Ada support for OpenAPI code generator","archived":false,"fork":false,"pushed_at":"2024-09-08T08:31:52.000Z","size":134480,"stargazers_count":27,"open_issues_count":4,"forks_count":3,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-09-08T17:12:19.895Z","etag":null,"topics":["ada","api","client","rest","server","swagger"],"latest_commit_sha":null,"homepage":"","language":"Ada","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stcarrez.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-09T14:41:19.000Z","updated_at":"2024-09-08T08:31:55.000Z","dependencies_parsed_at":"2024-02-01T20:08:58.887Z","dependency_job_id":"e1986872-e6fa-43af-bcd6-b8123a01809a","html_url":"https://github.com/stcarrez/swagger-ada","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/stcarrez/swagger-ada","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stcarrez%2Fswagger-ada","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stcarrez%2Fswagger-ada/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stcarrez%2Fswagger-ada/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stcarrez%2Fswagger-ada/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stcarrez","download_url":"https://codeload.github.com/stcarrez/swagger-ada/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stcarrez%2Fswagger-ada/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259519263,"owners_count":22870329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ada","api","client","rest","server","swagger"],"created_at":"2024-07-30T20:00:58.760Z","updated_at":"2025-06-12T18:33:55.513Z","avatar_url":"https://github.com/stcarrez.png","language":"Ada","funding_links":[],"categories":["Frameworks"],"sub_categories":["Web"],"readme":"# OpenAPI Ada Library\n\n[![Alire](https://img.shields.io/endpoint?url=https://alire.ada.dev/badges/openapi.json)](https://alire.ada.dev/crates/openapi)\n[![Alire](https://img.shields.io/endpoint?url=https://alire.ada.dev/badges/openapi_server.json)](https://alire.ada.dev/crates/openapi_server)\n[![Build Status](https://img.shields.io/endpoint?url=https://porion.vacs.fr/porion/api/v1/projects/openapi-ada/badges/build.json)](https://porion.vacs.fr/porion/projects/view/openapi-ada/summary)\n[![Test Status](https://img.shields.io/endpoint?url=https://porion.vacs.fr/porion/api/v1/projects/openapi-ada/badges/tests.json)](https://porion.vacs.fr/porion/projects/view/openapi-ada/xunits)\n[![Coverage](https://img.shields.io/endpoint?url=https://porion.vacs.fr/porion/api/v1/projects/openapi-ada/badges/coverage.json)](https://porion.vacs.fr/porion/projects/view/openapi-ada/summary)\n[![License](https://img.shields.io/badge/license-APACHE2-blue.svg)](LICENSE)\n[![GitLab](https://img.shields.io/badge/repo-GitLab-6C488A.svg)](https://gitlab.com/stcarrez/openapi-ada)\n[![Commits](https://img.shields.io/github/commits-since/stcarrez/swagger-ada/0.7.0.svg)](Commits)\n\n[OpenAPI Generator](https://gitlab.com/OpenAPITools/openapi-generator) is a code generator that supports generation of\nAPI client libraries, server stubs and documentation automatically\ngiven an [OpenAPI Spec](https://gitlab.com/OAI/OpenAPI-Specification).\n\nThe Ada client and server support has been integrated in [OpenAPI Generator](https://gitlab.com/OpenAPITools/openapi-generator).\n\nThe OpenAPI Ada library is a small support library for the Ada code generator\nprovided by OpenAPI Generator.  The library provides support to serialize the data,\nmake HTTP requests and support the [OpenAPI Spec](https://gitlab.com/OAI/OpenAPI-Specification)\nspecific operations or types.\n\n## Version 0.9.0   - Under development\n  - Update the openapi generator to version 7.11.0\n    - Fixed incorrect type declarations\n    - Added support for default values\n    - Fixed incorrect extraction of request body parameters for JSON and XML\n    - Added `x-ada-type-name` that can be put on the request body\n      to override a default request parameter name\n    - Fixed default request body parameter name to remove the\n      `_Type` that is added\n    - Updated GNAT project generation\n  - Allow to build and install without Alire\n  - Fix #21: Response 201..2xx are not considered successful\n\n## Version 0.8.0   - Sep 2024\n  - Cleanup build environment to drop configure\n  - Integrate swagger-ui-5.17.14\n  - Update the openapi generator to version 7.9.0\n\n[List all versions](https://gitlab.com/stcarrez/openapi-ada/blob/master/NEWS.md)\n\n## Using with Alire\n\nIf you are using [Alire](https://alire.ada.dev/) in your project, run the following command\nwithin your [Alire](https://alire.ada.dev/) project to use the library:\n\n### OpenAPI Client\n\n```\nalr with openapi\n```\n\nFor the HTTP connection, you can either use AWS or Curl and run one of the following commands:\n\n```\nalr with utilada_curl\nalr with utilada_aws\n```\n\n### OpenAPI Server\n\n```\nalr with openapi_server\n```\n\nFor the server part, you must choose a servlet web container that will handle the requests.\nTwo web server implementations are provided:\n\n* [AWS](https://github.com/AdaCore/aws)\n* [EWS](https://github.com/simonjwright/ews)\n\nand you should run one of the following `alr` command depending on your choice:\n\n```\nalr with servletada_aws\nalr with servletada_ews\n```\n\n## Using without Alire\n\nIf you don't have [Alire](https://alire.ada.dev/) or want to build and install the library\non a specific place, run a `setup` command to configure the build as well as installation\ndirectory.\n\nThe OpenAPI Ada library provides support for client and server.  The client part has\nless constraints than the server part which needs more components.\n\nThe `HAVE_ALIRE` configuration allows you to disable the build with [Alire](https://alire.ada.dev/),\nthe `HAVE_SERVER` controls whether you want to build and get the support for the server part,\nthe `HAVE_AWS` controls the support for AWS, `HAVE_CURL` the support for Curl in the client part\nand `HAVE_EWS` controls the support for EWS as server.\n\n```\nmake setup BUILD=debug PREFIX=/build/install HAVE_ALIRE=no HAVE_EWS=no HAVE_AWS=yes \\\n    HAVE_SERVER=yes HAVE_CURL=no\n```\n\nSince this build method does not verify that all dependencies are met, make sure that you\nhave already built and install the following components and they are available to `gprbuild`\nthrough `ADA_PROJECT_PATH` if needed:\n\n* [Ada Utility Library](https://gitlab.com/stcarrez/ada-util/)\n\nThe server part needs the following components:\n\n* [Ada Servlet](https://gitlab.com/stcarrez/ada-servlet/)\n* [Ada Security Library](https://gitlab.com/stcarrez/ada-security/)\n* [Ada EL Library](https://gitlab.com/stcarrez/ada-el/)\n\nThen build, run the unit tests and install by using:\n\n```\nmake\nmake test\nmake install\n```\n\nTo use the installed libraries, make sure your `ADA_PROJECT_PATH` contains the directory\nwhere you installed the libraries (configured by the `PREFIX=\u003cpath\u003e` option in the setup phase).\nThe installed GNAT projects are the same as those used when using [Alire](https://alire.ada.dev/).\n\nThe git repository comes with a pre-compiled [OpenAPI Generator](https://gitlab.com/OpenAPITools/openapi-generator)\nthat will be installed in `/usr/local/share/openapi-ada/openapi-generator-cli.jar`.  To help in launching the\ngenerator, a script is installed in `/usr/local/bin/openapi-generator`.  You must have a Java JRE installed\nto be able to run the generator.\n\n## Docker\n\nA docker container is available for those who want to try OpenAPI Ada without installing\nand building all required packages.  To use the OpenAPI Ada docker container you can\nrun the following commands:\n\n```\nsudo docker pull ciceron/openapi-ada\n```\n\n## Using OpenAPI Ada\n\n\n### Generating the REST client from OpenAPI Spec\n\nThe command to generate an Ada REST client is the following:\n```\n  alr exec -- openapi-generate-client -i my-api.yaml \\\n       --additional-properties projectName=MyProject \\\n       --additional-properties openApiName=OpenAPI \\\n       --additional-properties httpSupport=Curl \\\n       --model-package MyProject.MyModule -o .\n```\n\nwhere *my-api.yaml* is the OpenAPI specification file that describes your API,\n*MyProject* is the name of the GNAT project to use,\n*MyProject.MyModule* is the name of the Ada package that will be the parent\npackage of the generated Ada packages.\n\nThe generator will create several files in *client/src/client* with basically\ntwo packages: *MyProject.MyModule*.Models and *MyProject.MyModule*.Clients.\nThe **Models** child package will contain the type definitions for the\nAPI operations describes in the YAML file and the **Clients** child package\nwill contain the *Client_Type* tagged record with the API operations to\ninvoke the REST API.\n\nFor example, if the YAML description file contains the following API\noperation:\n```\nopenapi: 3.0.0\nservers:\n  - url: 'https://todo.vacs.fr/v1'\n  - url: 'http://todo.vacs.fr/v1'\ninfo:\n  title: Todo API\n  description: Todo API\n  version: 1.0.0\n  termsOfService: 'https://todo.vacs.fr/terms/'\n  contact:\n    email: Stephane.Carrez@gmail.com\n  license:\n    name: Apache 2.0\n    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'\ntags:\n  - name: tasks\n    description: Tasks\npaths:\n  /:\n    get:\n      tags:\n        - tasks\n      summary: Redirect to the UI\n      description: |\n        Default operation to redirect to the UI index page.\n      operationId: redirectTodos\n      responses:\n        '302':\n          description: redirect to the UI page\n  /todos:\n    get:\n      tags:\n        - tasks\n      summary: List the available tasks\n      description: |\n        The list of tasks can be filtered by their status.\n      operationId: listTodos\n      parameters:\n        - name: status\n          in: query\n          description: Filters the tasks by their status\n          required: false\n          schema:\n            type: string\n            enum:\n              - done\n              - waiting\n              - working\n              - all\n      responses:\n        '200':\n          description: successful operation\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  $ref: '#/components/schemas/Todo'\n        '400':\n          description: Invalid status value\n      security:\n        - todo_auth:\n            - 'read:todo'\nsecurity:\n  - todo_auth: []\nexternalDocs:\n  description: Find out more about Swagger\n  url: 'http://swagger.io'\ncomponents:\n  securitySchemes:\n    todo_auth:\n      type: oauth2\n      flows:\n        password:\n          tokenUrl: 'http://localhost:8080/v1/oauth/token'\n          scopes:\n            'write:todo': Write a todo\n            'read:todo': Read a todo\n  schemas:\n    Todo:\n      type: object\n      properties:\n        id:\n          type: integer\n          format: int64\n          description: The todo identifier\n        title:\n          type: string\n          description: The todo title\n        create_date:\n          type: string\n          format: date-time\n          description: The todo creation date\n        done_date:\n          type: string\n          format: date-time\n          description: The todo resolution date\n        status:\n          type: string\n          description: The todo state\n          enum:\n            - waiting\n            - working\n            - done\n      required:\n        - id\n        - title\n        - status\n        - create_date\n      example:\n        id: 23\n        title: Make the FOSDEM presentation\n        description: password\n        status: working\n        create_date: '2017-12-24T00:00:00.000Z'\n      xml:\n        name: Todo\n```\n\nThe generator will generate the following Ada code in the *Models* child package:\n```\npackage Todos.Models is\n   ...\n   type Todo_Type is\n     record\n       Id : OpenAPI.Long;\n       Title : OpenAPI.UString;\n       Create_Date : OpenAPI.Datetime;\n       Done_Date : OpenAPI.Nullable_Date;\n       Status : OpenAPI.UString;\n     end record;\n     ...\nend Todos.Models;\n```\n\nand the following code in the *Clients* child package:\n\n```\npackage Todos.Clients is\n   ...\n   type Client_Type is new OpenAPI.Clients.Client_Type with null record;\n   --  List the available tasks\n   --  The list of tasks can be filtered by their status.\n   procedure List_Todos\n      (Client : in out Client_Type;\n       Status : in OpenAPI.Nullable_UString;\n       Result : out Todos.Models.Todo_Type_Vectors.Vector);\n\n   --  Redirect to the UI\n   --  Default operation to redirect to the UI index page.\n   procedure Redirect_Todos\n      (Client : in out Client_Type);\n   ...\nend Todos.Clients;\n```\n\n### Initialization\n\nThe HTTP/REST support is provided by [Ada Util](https://gitlab.com/stcarrez/ada-util)\nand encapsulated by [OpenAPI Ada](https://gitlab.com/stcarrez/openapi-ada).  This support\nis either based on Curl or on [AWS](https://libre.adacore.com/libre/tools/aws/).\nThe OpenAPI code generator uses Curl by default and this can be changed when running\nthe `openapi-generator` tool and changing the following option:\n\n```\n       --additional-properties httpSupport=aws\n```\n\n\nIf you want to use Curl, the initialization should use the following:\n\n```\n   Util.Http.Clients.Curl.Register;\n```\n\nBut if you want to use [AWS](https://libre.adacore.com/libre/tools/aws/), you will initialize with:\n\n```\n   Util.Http.Clients.AWS.Register;\n```\n\nCurl may be easier to start with because [AWS](https://libre.adacore.com/libre/tools/aws/)\ndoes not support HTTP DELETE operation except in some latest version.\n\nAfter the initialization is done, you will declare a client instance to access\nthe API operations:\n\n```\n   C : Todos.Clients.Client_Type;\n```\n\nThe 'Client_Type' is the generated type that will implement the operations\ndescribed in the OpenAPI description file.\n\nAnd you should initialize the server base URI you want to connect to:\n\n```\n  C.Set_Server (\"http://localhost:8080/v1\");\n```\n\nAt this stage, you can use the generated operation.\n\n### Calling an operation\n\nLet's retrieve some todo list by calling the 'List_Todo' operation.\nThis operation needs an integer as input parameter and returns a 'Pet_Type'\nobject that contains all the pet information.   You will first declare\nthe pet instance as follows:\n\n```\n  List     : Todos.Models.Todo_Type_Vectors.Vector;\n```\n\nAnd then call the 'Get_Pet_By_Id' operation:\n\n```\n  C.List_Todos ((Is_Null =\u003e True, Value =\u003e \u003c\u003e), List);\n```\n\nAt this stage, you can access the list of todos:\n\n```\nprocedure Print (Todo : in Todos.Models.Todo_Type) is\nbegin\n   Put (OpenAPI.Long'Image (Todo.Id));\n   Set_Col (6);\n   Put (OpenAPI.To_String (Todo.Status));\n   Set_Col (15);\n   Put (Ada.Calendar.Formatting.Image (Todo.Create_Date));\n   Set_Col (40);\n   if Todo.Done_Date.Is_Null then\n      Put (\"-\");\n   else\n      Put (Ada.Calendar.Formatting.Image (Todo.Done_Date.Value));\n   end if;\n   Set_Col (60);\n   Put (OpenAPI.To_String (Todo.Title));\n   New_Line;\nend Print;\n\n  for T of List loop\n     Print (T);\n  end loop;\n```\n\n## Documentation\n\nThe OpenAPI Ada sources as well as a wiki documentation is provided on:\n\n- [Tutorial](https://gitlab.com/stcarrez/openapi-ada/blob/master/docs/Tutorial.md)\n- [Writing REST APIs with OpenAPI and Swagger Ada](https://www.slideshare.net/StephaneCarrez1/writing-rest-apis-with-openapi-and-swagger-ada/StephaneCarrez1/writing-rest-apis-with-openapi-and-swagger-ada)\n\n## Examples\n\n- [Todo API - OpenAPI Ada Server](https://github.com/stcarrez/swagger-ada-todo)\n- [Ada OpenAI](https://gitlab.com/stcarrez/ada-openai)\n- [OpenAI Image Generation](https://gitlab.com/stcarrez/openai-image)\n- [OpenAI Chat](https://gitlab.com/stcarrez/openai-chat)\n- [OpenAI Completion](https://gitlab.com/stcarrez/openai-completion)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstcarrez%2Fswagger-ada","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstcarrez%2Fswagger-ada","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstcarrez%2Fswagger-ada/lists"}