From a1af8e86806042856343e74bc09e5caae9e11290 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 15 Oct 2024 19:00:57 +0200 Subject: [PATCH 01/10] Create Camara-OAS-Sections-Guidelines.md --- .../Camara-OAS-Sections-Guidelines.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 documentation/Camara-OAS-Sections-Guidelines.md diff --git a/documentation/Camara-OAS-Sections-Guidelines.md b/documentation/Camara-OAS-Sections-Guidelines.md new file mode 100644 index 00000000..ae292795 --- /dev/null +++ b/documentation/Camara-OAS-Sections-Guidelines.md @@ -0,0 +1,20 @@ +# CAMARA OAS Sections Guidelines + +## Table of Contents + + * [Introduction](#introduction) + * [Conventions](#conventions) + * [OAS Sections](#oas-sections) + + [OpenAPI Version](#version) + + [Info Object](#info-object) + + + [Title](#title) + + + [Description](#description) + + + [Version](#version) + + + [Terms of service](#tos) + + + [Contact information](#contact) + + + [License](#license) + +## Introduction + +## Conventions +The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. From 5b341b467de83596211ecac824b55c3b8b98010c Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 15 Oct 2024 19:13:10 +0200 Subject: [PATCH 02/10] Update Camara-OAS-Sections-Guidelines.md --- documentation/Camara-OAS-Sections-Guidelines.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/documentation/Camara-OAS-Sections-Guidelines.md b/documentation/Camara-OAS-Sections-Guidelines.md index ae292795..3a5ff91a 100644 --- a/documentation/Camara-OAS-Sections-Guidelines.md +++ b/documentation/Camara-OAS-Sections-Guidelines.md @@ -13,8 +13,15 @@ + + [Terms of service](#tos) + + [Contact information](#contact) + + [License](#license) + + [Servers](#servers) + + [Paths](#paths) + + [Components](#components) + + [Security](#security) + + [Tags](#tags) + + [External Documentation](#ext-doc) ## Introduction +Camara uses OpenAPI Specification (OAS) to describe its APIs. The below guidelines specify the restrictions or conventions to be followed within the OAS yaml by all Camara APIs. ## Conventions The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. From f2bb086e48dbaa91f12d6f51395adbd6285a618f Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 15 Oct 2024 19:20:45 +0200 Subject: [PATCH 03/10] Update Camara-OAS-Sections-Guidelines.md --- .../Camara-OAS-Sections-Guidelines.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/documentation/Camara-OAS-Sections-Guidelines.md b/documentation/Camara-OAS-Sections-Guidelines.md index 3a5ff91a..dc73c1ba 100644 --- a/documentation/Camara-OAS-Sections-Guidelines.md +++ b/documentation/Camara-OAS-Sections-Guidelines.md @@ -7,15 +7,21 @@ * [OAS Sections](#oas-sections) + [OpenAPI Version](#version) + [Info Object](#info-object) - + + [Title](#title) - + + [Description](#description) - + + [Version](#version) - + + [Terms of service](#tos) - + + [Contact information](#contact) - + + [License](#license) + + [Title](#title) + + [Description](#description) + + [Version](#version) + + [Terms of service](#tos) + + [Contact information](#contact) + + [License](#license) + [Servers](#servers) + [Paths](#paths) + [Components](#components) + + [Schemas ](#schemes) + + [Responses](#responses) + + [Parameters](#parameters) + + [Request bodies](#req-bodies) + + [Headers](#headers) + + [Security schemes](#sec-schemes) + [Security](#security) + [Tags](#tags) + [External Documentation](#ext-doc) From 707dcdc3f32256789470cc4600220d831a8d5dc6 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 15 Oct 2024 20:39:41 +0200 Subject: [PATCH 04/10] Update Camara-OAS-Sections-Guidelines.md --- .../Camara-OAS-Sections-Guidelines.md | 48 ++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/documentation/Camara-OAS-Sections-Guidelines.md b/documentation/Camara-OAS-Sections-Guidelines.md index dc73c1ba..9a0f70e4 100644 --- a/documentation/Camara-OAS-Sections-Guidelines.md +++ b/documentation/Camara-OAS-Sections-Guidelines.md @@ -13,6 +13,7 @@ + [Terms of service](#tos) + [Contact information](#contact) + [License](#license) + + [Extension field](#ext-field) + [Servers](#servers) + [Paths](#paths) + [Components](#components) @@ -27,7 +28,52 @@ + [External Documentation](#ext-doc) ## Introduction -Camara uses OpenAPI Specification (OAS) to describe its APIs. The below guidelines specify the restrictions or conventions to be followed within the OAS yaml by all Camara APIs. +Camara uses OpenAPI Specification (OAS) to describe its APIs. The below guidelines specify the restrictions or conventions to be followed within the OAS yaml by all Camara APIs (referred below simply as APIs). ## Conventions The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. + +## OAS Sections + +### OpenAPI Version +APIs shall use the OAS version 3.0.3. + +### Info Object +An example of the info object is shown below: +``` +info: + title: Number Verification + description: | + This API allows to verify that the provided mobile phone number is the one used in the device. It + verifies that the user is using a device with the same mobile phone number as it is declared. + version: 1.0.1 + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + x-camara-commonalities: 0.4.0 + +``` +#### Title +Title should describe the API but shall not include the term "API" at the begining or at the end. + +#### Description + +#### Version +APIs shall use the [versioning-format](https://lf-camaraproject.atlassian.net/wiki/x/3yLe) as specified by the release management working group. + +#### Terms of service +Terms of service shall not be included. API providers may add this content when documenting their APIs. + +#### Contact information +Contact information shall not be includeds. API providers may add this content when documenting their APIs. + +#### License +The license object shall include the following fields: +``` +license + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html +``` + +#### Extension field +The API shall specify the commonalities release number they are compliant to, by including the x-camara-commonalities extension field. From ae1cec9ad5cc56d8e1a5c544b8ba6b5aef246993 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 15 Oct 2024 20:45:15 +0200 Subject: [PATCH 05/10] Update Camara-OAS-Sections-Guidelines.md --- documentation/Camara-OAS-Sections-Guidelines.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/Camara-OAS-Sections-Guidelines.md b/documentation/Camara-OAS-Sections-Guidelines.md index 9a0f70e4..f5974ec2 100644 --- a/documentation/Camara-OAS-Sections-Guidelines.md +++ b/documentation/Camara-OAS-Sections-Guidelines.md @@ -54,9 +54,10 @@ info: ``` #### Title -Title should describe the API but shall not include the term "API" at the begining or at the end. +API name shall be specified in the title but this shall not include the term "API" in it. #### Description +Description should shortly describe the API. #### Version APIs shall use the [versioning-format](https://lf-camaraproject.atlassian.net/wiki/x/3yLe) as specified by the release management working group. From cfa4ba9581cfb394adf90719fa2ce32c64c96406 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 15 Oct 2024 20:56:24 +0200 Subject: [PATCH 06/10] Update Camara-OAS-Sections-Guidelines.md --- documentation/Camara-OAS-Sections-Guidelines.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/documentation/Camara-OAS-Sections-Guidelines.md b/documentation/Camara-OAS-Sections-Guidelines.md index f5974ec2..45359b8f 100644 --- a/documentation/Camara-OAS-Sections-Guidelines.md +++ b/documentation/Camara-OAS-Sections-Guidelines.md @@ -78,3 +78,15 @@ license #### Extension field The API shall specify the commonalities release number they are compliant to, by including the x-camara-commonalities extension field. + +### Servers +The servers object shall have the following content: +``` +servers: + - url: {apiRoot}// + variables: + apiRoot: + default: http://localhost:9091 + description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` +``` +API-name and API-Version shall be same as the [Title](#title) and [Version](#version) in the Info Object respectively. From ca98362059c2302805845d6507881cc85c9fb4b8 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 15 Oct 2024 21:05:50 +0200 Subject: [PATCH 07/10] Update Camara-OAS-Sections-Guidelines.md --- documentation/Camara-OAS-Sections-Guidelines.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/documentation/Camara-OAS-Sections-Guidelines.md b/documentation/Camara-OAS-Sections-Guidelines.md index 45359b8f..7513bfb2 100644 --- a/documentation/Camara-OAS-Sections-Guidelines.md +++ b/documentation/Camara-OAS-Sections-Guidelines.md @@ -54,10 +54,10 @@ info: ``` #### Title -API name shall be specified in the title but this shall not include the term "API" in it. +Title describes the API shortly. The title shall not include the term "API" in it. #### Description -Description should shortly describe the API. +Description should provide a slightly longer description of the API as compared to the title. #### Version APIs shall use the [versioning-format](https://lf-camaraproject.atlassian.net/wiki/x/3yLe) as specified by the release management working group. @@ -89,4 +89,9 @@ servers: default: http://localhost:9091 description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` ``` -API-name and API-Version shall be same as the [Title](#title) and [Version](#version) in the Info Object respectively. +API-name is what is specified as the base path, prior to the API version, in the servers[*].url property. For example, from /location-verification/v0, it would be location-verification. +If more than one server object instances are listed, each servers[*].url property must have the same string for the API name and version in respective instance + +API-Version shall be same as the [Version](#version) in the info object. + +### Paths From 7975033659170d6ad507aa1fb6c4ef5703753e97 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 15 Oct 2024 21:20:26 +0200 Subject: [PATCH 08/10] Update Camara-OAS-Sections-Guidelines.md --- documentation/Camara-OAS-Sections-Guidelines.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/documentation/Camara-OAS-Sections-Guidelines.md b/documentation/Camara-OAS-Sections-Guidelines.md index 7513bfb2..07d9152d 100644 --- a/documentation/Camara-OAS-Sections-Guidelines.md +++ b/documentation/Camara-OAS-Sections-Guidelines.md @@ -89,8 +89,17 @@ servers: default: http://localhost:9091 description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` ``` -API-name is what is specified as the base path, prior to the API version, in the servers[*].url property. For example, from /location-verification/v0, it would be location-verification. -If more than one server object instances are listed, each servers[*].url property must have the same string for the API name and version in respective instance +API-Name +API-Name is what is specified as the base path, prior to the API version, in the servers[*].url property. If more than one server object instances are listed, each servers[*].url property must have the same string for the API name and version in respective instance + +For the below example, the API-name would be location-verification. + ``` + /location-verification/v0 +``` + +
+ +API-Version
API-Version shall be same as the [Version](#version) in the info object. From 0d16b91710ce433c014ccaea5e65f3639c35a94d Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 15 Oct 2024 21:31:36 +0200 Subject: [PATCH 09/10] Update Camara-OAS-Sections-Guidelines.md --- documentation/Camara-OAS-Sections-Guidelines.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/documentation/Camara-OAS-Sections-Guidelines.md b/documentation/Camara-OAS-Sections-Guidelines.md index 07d9152d..17fd54d5 100644 --- a/documentation/Camara-OAS-Sections-Guidelines.md +++ b/documentation/Camara-OAS-Sections-Guidelines.md @@ -57,7 +57,7 @@ info: Title describes the API shortly. The title shall not include the term "API" in it. #### Description -Description should provide a slightly longer description of the API as compared to the title. +No special restrictions specified in Camara. #### Version APIs shall use the [versioning-format](https://lf-camaraproject.atlassian.net/wiki/x/3yLe) as specified by the release management working group. @@ -104,3 +104,5 @@ For the below example, the API-name would be location-verification. API-Version shall be same as the [Version](#version) in the info object. ### Paths +No special restrictions or changes specified in Camara. + From 191dfe1ae5760727b2ed97c278112d1d0b60fa17 Mon Sep 17 00:00:00 2001 From: Shilpa Padgaonkar <77152136+shilpa-padgaonkar@users.noreply.github.com> Date: Tue, 15 Oct 2024 21:32:06 +0200 Subject: [PATCH 10/10] Update Camara-OAS-Sections-Guidelines.md --- documentation/Camara-OAS-Sections-Guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/Camara-OAS-Sections-Guidelines.md b/documentation/Camara-OAS-Sections-Guidelines.md index 17fd54d5..92b690f3 100644 --- a/documentation/Camara-OAS-Sections-Guidelines.md +++ b/documentation/Camara-OAS-Sections-Guidelines.md @@ -66,7 +66,7 @@ APIs shall use the [versioning-format](https://lf-camaraproject.atlassian.net/wi Terms of service shall not be included. API providers may add this content when documenting their APIs. #### Contact information -Contact information shall not be includeds. API providers may add this content when documenting their APIs. +Contact information shall not be included. API providers may add this content when documenting their APIs. #### License The license object shall include the following fields: