From 33021c8ff617fc45c111ac3dae2931f0cee6d000 Mon Sep 17 00:00:00 2001 From: Josephine Qiu Date: Tue, 19 Oct 2021 19:51:01 +0800 Subject: [PATCH 1/6] Create Sample Directory Structure for Swagger --- .../Sample Directory Structure for Swagger | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 documentation/Sample Directory Structure for Swagger diff --git a/documentation/Sample Directory Structure for Swagger b/documentation/Sample Directory Structure for Swagger new file mode 100644 index 000000000000..2399afe988a3 --- /dev/null +++ b/documentation/Sample Directory Structure for Swagger @@ -0,0 +1,57 @@ +When creating a OpenAPI specification (a.k.a Swagger), the sample directory structure you have to follow is represented here: + + +\---specification + +---automation + | \---resource-manager + | \---Microsoft.Automation + | | \---stable + | | \---2015-10-31 + | | \---examples + | \---readme.md + +---batch + | +---data-plane + | | \---Microsoft.Batch + | | | \---stable + | | | | +---2015-12-01.2.2 + | | | | +---2016-02-01.3.0 + | | | | +---2016-07-01.3.1 + | | | | +---2017-01-01.4.0 + | | | | \---examples + | | | \---preview + | | | \---2017-05-01.5.0 + | | \---readme.md + | \---resource-manager + | \---Microsoft.Batch + | | +---stable + | | +---2015-12-01 + | | +---2017-01-01 + | | \---examples + | | +---2017-05-01 + | | \---examples + | \---readme.md + +---billing + \---resource-manager + \---Microsoft.Billing + | \---stable + | | +---2017-02-27-preview + | | \---examples + | +---preview + | \---2017-04-24-preview + | \---examples + \---readme.md + + + +Alternatively, you can always look at any of the [existing resource providers](https://github.com/Azure/azure-rest-api-specs/tree/master/specification) and follow the same structure. Sample configuration files can be found [here](/\(WIP\)-Welcome-Service-Partners!/Sample-ReadME/Sample-Files). + +In the directory structure above you will notice that there are a few key things that are needed: + 1. A `service team name folder` under the `specification` folder (ex: automation or batch or billing in the example above). + 2. A `resource-manager` and/or `data-plane` folder under your service team name folder. Use the `resource-manager` (for ARM resources) and `data-plane` (for everything else) . + 3. The autorest configuration file ([`readme.md`](/\(WIP\)-Welcome-Service-Partners!/Sample-ReadME)) for the resource provider should be inside the `resource-manager` and `data-plane` folders. Create your readme.md and sdk config readme.mds' following the same pattern as other service teams ([`sample`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/YourServiceName.json)). + 4. A `Microsoft.ResourceProviderName` folder, also inside the `resource-manager` and `data-plane` folders. This folder will hold your OpenAPI specifications and examples (ex: Microsoft.Automation, Microsoft.Batch in the example above). + 5. A `stable` and/or `preview` folder under the resource provider folder. Swaggers of service/features/resource type endpoints in **Public Preview** go to `preview` folder; swaggers of ONLY **GA** service/features/resource types/endpoints go to `stable` folder. Swaggers and updates public in the master branch of the public repository (azure-rest-api-specs) should be treated as contract with Azure customers, need to meet quality criteria defined with [Swagger KPIs](https://aka.ms/swaggerkpis), and strictly follow [Azure Breaking Changes Policy](https://aka.ms/AzBreakingChangesPolicy) for further updating, no matter in `preview` folder or `stable` folder. + 6. Your API version folder goes under the `stable` and `preview` folders. This folder will contain the OpenAPI specifications and an example folder. Please follow the **`YYYY-MM-DD`** format. And please **ensure consistency between the API version in the OpenAPI specifications and API version in the folder structure**. + 7. An examples folder is under your API version folder. The example folder will contain the [`x-ms-examples`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md) files. + +Go back to [Getting started with OpenAPI specifications](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/Getting%20started%20with%20OpenAPI%20specifications.md). From a16000fd1638848039307b05a808ade567f790ef Mon Sep 17 00:00:00 2001 From: Josephine Qiu Date: Tue, 19 Oct 2021 19:54:03 +0800 Subject: [PATCH 2/6] Delete Sample Directory Structure for Swagger --- .../Sample Directory Structure for Swagger | 57 ------------------- 1 file changed, 57 deletions(-) delete mode 100644 documentation/Sample Directory Structure for Swagger diff --git a/documentation/Sample Directory Structure for Swagger b/documentation/Sample Directory Structure for Swagger deleted file mode 100644 index 2399afe988a3..000000000000 --- a/documentation/Sample Directory Structure for Swagger +++ /dev/null @@ -1,57 +0,0 @@ -When creating a OpenAPI specification (a.k.a Swagger), the sample directory structure you have to follow is represented here: - - -\---specification - +---automation - | \---resource-manager - | \---Microsoft.Automation - | | \---stable - | | \---2015-10-31 - | | \---examples - | \---readme.md - +---batch - | +---data-plane - | | \---Microsoft.Batch - | | | \---stable - | | | | +---2015-12-01.2.2 - | | | | +---2016-02-01.3.0 - | | | | +---2016-07-01.3.1 - | | | | +---2017-01-01.4.0 - | | | | \---examples - | | | \---preview - | | | \---2017-05-01.5.0 - | | \---readme.md - | \---resource-manager - | \---Microsoft.Batch - | | +---stable - | | +---2015-12-01 - | | +---2017-01-01 - | | \---examples - | | +---2017-05-01 - | | \---examples - | \---readme.md - +---billing - \---resource-manager - \---Microsoft.Billing - | \---stable - | | +---2017-02-27-preview - | | \---examples - | +---preview - | \---2017-04-24-preview - | \---examples - \---readme.md - - - -Alternatively, you can always look at any of the [existing resource providers](https://github.com/Azure/azure-rest-api-specs/tree/master/specification) and follow the same structure. Sample configuration files can be found [here](/\(WIP\)-Welcome-Service-Partners!/Sample-ReadME/Sample-Files). - -In the directory structure above you will notice that there are a few key things that are needed: - 1. A `service team name folder` under the `specification` folder (ex: automation or batch or billing in the example above). - 2. A `resource-manager` and/or `data-plane` folder under your service team name folder. Use the `resource-manager` (for ARM resources) and `data-plane` (for everything else) . - 3. The autorest configuration file ([`readme.md`](/\(WIP\)-Welcome-Service-Partners!/Sample-ReadME)) for the resource provider should be inside the `resource-manager` and `data-plane` folders. Create your readme.md and sdk config readme.mds' following the same pattern as other service teams ([`sample`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/YourServiceName.json)). - 4. A `Microsoft.ResourceProviderName` folder, also inside the `resource-manager` and `data-plane` folders. This folder will hold your OpenAPI specifications and examples (ex: Microsoft.Automation, Microsoft.Batch in the example above). - 5. A `stable` and/or `preview` folder under the resource provider folder. Swaggers of service/features/resource type endpoints in **Public Preview** go to `preview` folder; swaggers of ONLY **GA** service/features/resource types/endpoints go to `stable` folder. Swaggers and updates public in the master branch of the public repository (azure-rest-api-specs) should be treated as contract with Azure customers, need to meet quality criteria defined with [Swagger KPIs](https://aka.ms/swaggerkpis), and strictly follow [Azure Breaking Changes Policy](https://aka.ms/AzBreakingChangesPolicy) for further updating, no matter in `preview` folder or `stable` folder. - 6. Your API version folder goes under the `stable` and `preview` folders. This folder will contain the OpenAPI specifications and an example folder. Please follow the **`YYYY-MM-DD`** format. And please **ensure consistency between the API version in the OpenAPI specifications and API version in the folder structure**. - 7. An examples folder is under your API version folder. The example folder will contain the [`x-ms-examples`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md) files. - -Go back to [Getting started with OpenAPI specifications](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/Getting%20started%20with%20OpenAPI%20specifications.md). From 0426d39c2a691504bd745052d2055310118ec05a Mon Sep 17 00:00:00 2001 From: Josephine Qiu Date: Tue, 19 Oct 2021 19:56:03 +0800 Subject: [PATCH 3/6] Create Sample Directory Structure for Swagger --- .../Sample Directory Structure for Swagger | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 documentation/Sample Directory Structure for Swagger diff --git a/documentation/Sample Directory Structure for Swagger b/documentation/Sample Directory Structure for Swagger new file mode 100644 index 000000000000..2399afe988a3 --- /dev/null +++ b/documentation/Sample Directory Structure for Swagger @@ -0,0 +1,57 @@ +When creating a OpenAPI specification (a.k.a Swagger), the sample directory structure you have to follow is represented here: + + +\---specification + +---automation + | \---resource-manager + | \---Microsoft.Automation + | | \---stable + | | \---2015-10-31 + | | \---examples + | \---readme.md + +---batch + | +---data-plane + | | \---Microsoft.Batch + | | | \---stable + | | | | +---2015-12-01.2.2 + | | | | +---2016-02-01.3.0 + | | | | +---2016-07-01.3.1 + | | | | +---2017-01-01.4.0 + | | | | \---examples + | | | \---preview + | | | \---2017-05-01.5.0 + | | \---readme.md + | \---resource-manager + | \---Microsoft.Batch + | | +---stable + | | +---2015-12-01 + | | +---2017-01-01 + | | \---examples + | | +---2017-05-01 + | | \---examples + | \---readme.md + +---billing + \---resource-manager + \---Microsoft.Billing + | \---stable + | | +---2017-02-27-preview + | | \---examples + | +---preview + | \---2017-04-24-preview + | \---examples + \---readme.md + + + +Alternatively, you can always look at any of the [existing resource providers](https://github.com/Azure/azure-rest-api-specs/tree/master/specification) and follow the same structure. Sample configuration files can be found [here](/\(WIP\)-Welcome-Service-Partners!/Sample-ReadME/Sample-Files). + +In the directory structure above you will notice that there are a few key things that are needed: + 1. A `service team name folder` under the `specification` folder (ex: automation or batch or billing in the example above). + 2. A `resource-manager` and/or `data-plane` folder under your service team name folder. Use the `resource-manager` (for ARM resources) and `data-plane` (for everything else) . + 3. The autorest configuration file ([`readme.md`](/\(WIP\)-Welcome-Service-Partners!/Sample-ReadME)) for the resource provider should be inside the `resource-manager` and `data-plane` folders. Create your readme.md and sdk config readme.mds' following the same pattern as other service teams ([`sample`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/YourServiceName.json)). + 4. A `Microsoft.ResourceProviderName` folder, also inside the `resource-manager` and `data-plane` folders. This folder will hold your OpenAPI specifications and examples (ex: Microsoft.Automation, Microsoft.Batch in the example above). + 5. A `stable` and/or `preview` folder under the resource provider folder. Swaggers of service/features/resource type endpoints in **Public Preview** go to `preview` folder; swaggers of ONLY **GA** service/features/resource types/endpoints go to `stable` folder. Swaggers and updates public in the master branch of the public repository (azure-rest-api-specs) should be treated as contract with Azure customers, need to meet quality criteria defined with [Swagger KPIs](https://aka.ms/swaggerkpis), and strictly follow [Azure Breaking Changes Policy](https://aka.ms/AzBreakingChangesPolicy) for further updating, no matter in `preview` folder or `stable` folder. + 6. Your API version folder goes under the `stable` and `preview` folders. This folder will contain the OpenAPI specifications and an example folder. Please follow the **`YYYY-MM-DD`** format. And please **ensure consistency between the API version in the OpenAPI specifications and API version in the folder structure**. + 7. An examples folder is under your API version folder. The example folder will contain the [`x-ms-examples`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md) files. + +Go back to [Getting started with OpenAPI specifications](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/Getting%20started%20with%20OpenAPI%20specifications.md). From e13f8d977c06d224e72593b7c4b38bd8679641cb Mon Sep 17 00:00:00 2001 From: Josephine Qiu Date: Tue, 19 Oct 2021 20:04:51 +0800 Subject: [PATCH 4/6] Update Getting started with OpenAPI specifications.md --- .../Getting started with OpenAPI specifications.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/documentation/Getting started with OpenAPI specifications.md b/documentation/Getting started with OpenAPI specifications.md index 438d60ea1bf9..65a8650a2d61 100644 --- a/documentation/Getting started with OpenAPI specifications.md +++ b/documentation/Getting started with OpenAPI specifications.md @@ -9,7 +9,9 @@ Currently, we only support `OpenAPI Specification 2.0` or `Swagger V2.0`. ### Helpful Resources * **[`Understanding the GitHub flow`](https://guides.github.com/introduction/flow/)** -* **[`Microsoft REST-API guidelines`](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md)** +* **[`Microsoft REST-API guidelines`](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md)**] +* **[`Resource Provider Guidelines`](https://aka.ms/rpguidelines)** +* **[`Sample directory structure for swagger`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/Sample-Directory-Structure-for-Swagger)** * **[`Structure of a Swagger specification`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/creating-swagger.md)** * **[`Sample Swagger specification`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/YourServiceName.json)** * **[`Sample Readme.md`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/samplefiles/samplereadme.md)** @@ -19,5 +21,5 @@ Currently, we only support `OpenAPI Specification 2.0` or `Swagger V2.0`. * [`Validation checks through automated tools`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/openapi-authoring-automated-guidelines.md) * [`Validation checks done manually`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/openapi-authoring-manual-guidelines.md) * [`OAV Validation checks`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/Semantic-and-Model-Violations-Reference.md) -* **[`Breaking Changes guidelines`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/Breaking%20changes%20guidelines.md)** +* **[`Breaking Changes guidelines`](https://aka.ms/AzBreakingChangesPolicy)** * **[`x-ms-examples`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md)** From b6939eabf6b128d11a22e4c28141cb48eb8fa4de Mon Sep 17 00:00:00 2001 From: Josephine Qiu Date: Thu, 21 Oct 2021 08:53:55 +0800 Subject: [PATCH 5/6] Delete Sample Directory Structure for Swagger will reuse this wiki https://github.com/Azure/azure-rest-api-specs/wiki#directory-structure, instead of creating a new one. --- .../Sample Directory Structure for Swagger | 57 ------------------- 1 file changed, 57 deletions(-) delete mode 100644 documentation/Sample Directory Structure for Swagger diff --git a/documentation/Sample Directory Structure for Swagger b/documentation/Sample Directory Structure for Swagger deleted file mode 100644 index 2399afe988a3..000000000000 --- a/documentation/Sample Directory Structure for Swagger +++ /dev/null @@ -1,57 +0,0 @@ -When creating a OpenAPI specification (a.k.a Swagger), the sample directory structure you have to follow is represented here: - - -\---specification - +---automation - | \---resource-manager - | \---Microsoft.Automation - | | \---stable - | | \---2015-10-31 - | | \---examples - | \---readme.md - +---batch - | +---data-plane - | | \---Microsoft.Batch - | | | \---stable - | | | | +---2015-12-01.2.2 - | | | | +---2016-02-01.3.0 - | | | | +---2016-07-01.3.1 - | | | | +---2017-01-01.4.0 - | | | | \---examples - | | | \---preview - | | | \---2017-05-01.5.0 - | | \---readme.md - | \---resource-manager - | \---Microsoft.Batch - | | +---stable - | | +---2015-12-01 - | | +---2017-01-01 - | | \---examples - | | +---2017-05-01 - | | \---examples - | \---readme.md - +---billing - \---resource-manager - \---Microsoft.Billing - | \---stable - | | +---2017-02-27-preview - | | \---examples - | +---preview - | \---2017-04-24-preview - | \---examples - \---readme.md - - - -Alternatively, you can always look at any of the [existing resource providers](https://github.com/Azure/azure-rest-api-specs/tree/master/specification) and follow the same structure. Sample configuration files can be found [here](/\(WIP\)-Welcome-Service-Partners!/Sample-ReadME/Sample-Files). - -In the directory structure above you will notice that there are a few key things that are needed: - 1. A `service team name folder` under the `specification` folder (ex: automation or batch or billing in the example above). - 2. A `resource-manager` and/or `data-plane` folder under your service team name folder. Use the `resource-manager` (for ARM resources) and `data-plane` (for everything else) . - 3. The autorest configuration file ([`readme.md`](/\(WIP\)-Welcome-Service-Partners!/Sample-ReadME)) for the resource provider should be inside the `resource-manager` and `data-plane` folders. Create your readme.md and sdk config readme.mds' following the same pattern as other service teams ([`sample`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/YourServiceName.json)). - 4. A `Microsoft.ResourceProviderName` folder, also inside the `resource-manager` and `data-plane` folders. This folder will hold your OpenAPI specifications and examples (ex: Microsoft.Automation, Microsoft.Batch in the example above). - 5. A `stable` and/or `preview` folder under the resource provider folder. Swaggers of service/features/resource type endpoints in **Public Preview** go to `preview` folder; swaggers of ONLY **GA** service/features/resource types/endpoints go to `stable` folder. Swaggers and updates public in the master branch of the public repository (azure-rest-api-specs) should be treated as contract with Azure customers, need to meet quality criteria defined with [Swagger KPIs](https://aka.ms/swaggerkpis), and strictly follow [Azure Breaking Changes Policy](https://aka.ms/AzBreakingChangesPolicy) for further updating, no matter in `preview` folder or `stable` folder. - 6. Your API version folder goes under the `stable` and `preview` folders. This folder will contain the OpenAPI specifications and an example folder. Please follow the **`YYYY-MM-DD`** format. And please **ensure consistency between the API version in the OpenAPI specifications and API version in the folder structure**. - 7. An examples folder is under your API version folder. The example folder will contain the [`x-ms-examples`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md) files. - -Go back to [Getting started with OpenAPI specifications](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/Getting%20started%20with%20OpenAPI%20specifications.md). From deac94a5904f9cc3f2ebf1bf57f2b3875b223ff1 Mon Sep 17 00:00:00 2001 From: Josephine Qiu Date: Thu, 21 Oct 2021 08:54:52 +0800 Subject: [PATCH 6/6] Update Getting started with OpenAPI specifications.md reuse this wiki for sample directory https://github.com/Azure/azure-rest-api-specs/wiki#directory-structure --- documentation/Getting started with OpenAPI specifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/Getting started with OpenAPI specifications.md b/documentation/Getting started with OpenAPI specifications.md index 65a8650a2d61..9c7b7e746cbf 100644 --- a/documentation/Getting started with OpenAPI specifications.md +++ b/documentation/Getting started with OpenAPI specifications.md @@ -11,7 +11,7 @@ Currently, we only support `OpenAPI Specification 2.0` or `Swagger V2.0`. * **[`Understanding the GitHub flow`](https://guides.github.com/introduction/flow/)** * **[`Microsoft REST-API guidelines`](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md)**] * **[`Resource Provider Guidelines`](https://aka.ms/rpguidelines)** -* **[`Sample directory structure for swagger`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/Sample-Directory-Structure-for-Swagger)** +* **[`Sample directory structure for swagger`](https://github.com/Azure/azure-rest-api-specs/wiki#directory-structure)** * **[`Structure of a Swagger specification`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/creating-swagger.md)** * **[`Sample Swagger specification`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/samplefiles/Microsoft.YourServiceName/stable/YYYY-MM-DD/YourServiceName.json)** * **[`Sample Readme.md`](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/samplefiles/samplereadme.md)**