From 4b89cda1f10172e6c30215217ffcf6ac92c85555 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Mon, 15 Apr 2024 16:01:32 -0700 Subject: [PATCH 1/6] ongoing --- documentation/samplefiles-dp/ABOUT.md | 24 +++++++++++++++++++ documentation/samplefiles-dp/README.md | 5 ---- .../{readme.md => readmex.md} | 2 +- .../{readme.md => readmex.md} | 0 documentation/samplefiles/ABOUT.md | 15 ++++++++++++ .../{samplereadme.md => README.md} | 0 6 files changed, 40 insertions(+), 6 deletions(-) create mode 100644 documentation/samplefiles-dp/ABOUT.md delete mode 100644 documentation/samplefiles-dp/README.md rename documentation/samplefiles-dp/samplefiles-dp-for-multi-client/{readme.md => readmex.md} (99%) rename documentation/samplefiles-dp/samplefiles-dp-for-single-client/{readme.md => readmex.md} (100%) create mode 100644 documentation/samplefiles/ABOUT.md rename documentation/samplefiles/{samplereadme.md => README.md} (100%) diff --git a/documentation/samplefiles-dp/ABOUT.md b/documentation/samplefiles-dp/ABOUT.md new file mode 100644 index 000000000000..3c6e67ce94c9 --- /dev/null +++ b/documentation/samplefiles-dp/ABOUT.md @@ -0,0 +1,24 @@ +This `samplefiles-dp` directory contains sample AutoRest configuration files +for data-plane specs: `README.md`. +It also contains the sample hand-written OpenAPI specification files referenced by these files. + +You can learn more about AutoRest configuration files at +[aka.ms/azsdk/autorest](https://aka.ms/azsdk/autorest). + +> [!CAUTION] +> The example OpenAPI specification files in this directory are hand-written, +> which is a legacy, obsolete approach. For current approach refer to +> [aka.ms/azsdk/typespec](https://aka.ms/azsdk/typespec). + +For a case where a single SDK client is generated, +see [dataplane samples for single client](samplefiles-dp-for-single-client). +This is the default, common scenario. + +For a case where a multiple SDK clients are generated, +see [dataplane samples for multi client](samplefiles-dp-for-multi-client). +This is an advanced scenario. You can learn more about it at +[aka.ms/azsdk/spec-dirs#advanced-scenario-service-group](https://aka.ms/azsdk/spec-dirs#advanced-scenario-service-group). + +See also: [../samplefiles](../samplefiles) + + diff --git a/documentation/samplefiles-dp/README.md b/documentation/samplefiles-dp/README.md deleted file mode 100644 index 5765822006ba..000000000000 --- a/documentation/samplefiles-dp/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Dataplane Swagger Samples - -If the swagger will generate sdk with single client, please refer to [dataplane samples for single client](samplefiles-dp-for-single-client). (By default you will always use single client sample.) - -If the swagger will generate sdk with multi client, please refer to [dataplane samples for multi client](samplefiles-dp-for-multi-client). (You will only generate multi-client sdk when Arch Board asks you to do it.) \ No newline at end of file diff --git a/documentation/samplefiles-dp/samplefiles-dp-for-multi-client/readme.md b/documentation/samplefiles-dp/samplefiles-dp-for-multi-client/readmex.md similarity index 99% rename from documentation/samplefiles-dp/samplefiles-dp-for-multi-client/readme.md rename to documentation/samplefiles-dp/samplefiles-dp-for-multi-client/readmex.md index c19b1ba83f27..e50925ee78a7 100644 --- a/documentation/samplefiles-dp/samplefiles-dp-for-multi-client/readme.md +++ b/documentation/samplefiles-dp/samplefiles-dp-for-multi-client/readmex.md @@ -82,4 +82,4 @@ swagger-to-sdk: - repo: azure-sdk-for-python - repo: azure-sdk-for-java - repo: azure-sdk-for-net-track2 -``` \ No newline at end of file +``` diff --git a/documentation/samplefiles-dp/samplefiles-dp-for-single-client/readme.md b/documentation/samplefiles-dp/samplefiles-dp-for-single-client/readmex.md similarity index 100% rename from documentation/samplefiles-dp/samplefiles-dp-for-single-client/readme.md rename to documentation/samplefiles-dp/samplefiles-dp-for-single-client/readmex.md diff --git a/documentation/samplefiles/ABOUT.md b/documentation/samplefiles/ABOUT.md new file mode 100644 index 000000000000..5a02cb87e7a6 --- /dev/null +++ b/documentation/samplefiles/ABOUT.md @@ -0,0 +1,15 @@ +This `samplefiles` directory contains sample AutoRest configuration files: +`README.*.md`. It also contains the sample hand-written OpenAPI +specification files referenced by these files. + +Finally, the `./Microsoft.YourServiceName/stable/YYYY-MM-DD/scenarios/quickStart.yaml` is an [api-scenario](../api-scenario) sample. + +You can learn more about AutoRest configuration files at +[aka.ms/azsdk/autorest](https://aka.ms/azsdk/autorest). + +> [!CAUTION] +> The example OpenAPI specification files in this directory are hand-written, +> which is a legacy, obsolete approach. For current approach refer to +> [aka.ms/azsdk/typespec](https://aka.ms/azsdk/typespec). + +See also: [../samplefiles-dp](../samplefiles-dp) diff --git a/documentation/samplefiles/samplereadme.md b/documentation/samplefiles/README.md similarity index 100% rename from documentation/samplefiles/samplereadme.md rename to documentation/samplefiles/README.md From d9cf0cf9a0b043169f443f44151ec53ceb90dec5 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Mon, 15 Apr 2024 16:01:57 -0700 Subject: [PATCH 2/6] ongoing --- .../samplefiles-dp-for-multi-client/{readmex.md => README.md} | 0 .../samplefiles-dp-for-single-client/{readmex.md => README.md} | 2 +- documentation/samplefiles/ABOUT.md | 3 ++- 3 files changed, 3 insertions(+), 2 deletions(-) rename documentation/samplefiles-dp/samplefiles-dp-for-multi-client/{readmex.md => README.md} (100%) rename documentation/samplefiles-dp/samplefiles-dp-for-single-client/{readmex.md => README.md} (99%) diff --git a/documentation/samplefiles-dp/samplefiles-dp-for-multi-client/readmex.md b/documentation/samplefiles-dp/samplefiles-dp-for-multi-client/README.md similarity index 100% rename from documentation/samplefiles-dp/samplefiles-dp-for-multi-client/readmex.md rename to documentation/samplefiles-dp/samplefiles-dp-for-multi-client/README.md diff --git a/documentation/samplefiles-dp/samplefiles-dp-for-single-client/readmex.md b/documentation/samplefiles-dp/samplefiles-dp-for-single-client/README.md similarity index 99% rename from documentation/samplefiles-dp/samplefiles-dp-for-single-client/readmex.md rename to documentation/samplefiles-dp/samplefiles-dp-for-single-client/README.md index 2fe38bf1c326..0339d2b73fad 100644 --- a/documentation/samplefiles-dp/samplefiles-dp-for-single-client/readmex.md +++ b/documentation/samplefiles-dp/samplefiles-dp-for-single-client/README.md @@ -54,4 +54,4 @@ swagger-to-sdk: - repo: azure-sdk-for-python - repo: azure-sdk-for-java - repo: azure-sdk-for-net-track2 -``` \ No newline at end of file +``` diff --git a/documentation/samplefiles/ABOUT.md b/documentation/samplefiles/ABOUT.md index 5a02cb87e7a6..e1ffa28110b6 100644 --- a/documentation/samplefiles/ABOUT.md +++ b/documentation/samplefiles/ABOUT.md @@ -2,7 +2,8 @@ This `samplefiles` directory contains sample AutoRest configuration files: `README.*.md`. It also contains the sample hand-written OpenAPI specification files referenced by these files. -Finally, the `./Microsoft.YourServiceName/stable/YYYY-MM-DD/scenarios/quickStart.yaml` is an [api-scenario](../api-scenario) sample. +Finally, the `./Microsoft.YourServiceName/stable/YYYY-MM-DD/scenarios/quickStart.yaml` +is an [api-scenario](../api-scenario) sample. You can learn more about AutoRest configuration files at [aka.ms/azsdk/autorest](https://aka.ms/azsdk/autorest). From dbf536c951ae057e2d2cd98d4d89b23fbce0e665 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Mon, 15 Apr 2024 16:09:43 -0700 Subject: [PATCH 3/6] update --- documentation/api-scenario/readme.md | 15 +++++++++------ documentation/samplefiles-dp/ABOUT.md | 14 ++++++++++---- documentation/samplefiles/ABOUT.md | 17 +++++++++++------ 3 files changed, 30 insertions(+), 16 deletions(-) diff --git a/documentation/api-scenario/readme.md b/documentation/api-scenario/readme.md index 741d8a58a121..67fb52a746ff 100644 --- a/documentation/api-scenario/readme.md +++ b/documentation/api-scenario/readme.md @@ -1,6 +1,11 @@ # API Scenario Documentation -API Scenario is a YAML file defining RESTful API usage scenarios of your service with a sequence of API calls. API scenario can be used for service API functional test, API quality validation and SDK/CLIs test generation. +API Scenario is a YAML file defining RESTful API usage scenarios of your +service with a sequence of API calls. API scenario can be used for service +API functional test, API quality validation and SDK/CLIs test generation. + +API scenario is implemented in the [Azure/aov](https://github.com/Azure/oav) +repository. ## Features @@ -27,9 +32,7 @@ API Scenario is a YAML file defining RESTful API usage scenarios of your service - [API Scenario Runner Reference](./references/Runner.md) - [API Scenario JSON Schema](./references/v1.2/schema.json) -## Feedback +## Getting help -If you have any question or need support, feel free to contact us via: -- [StackOverflow](https://stackoverflow.microsoft.com/posts/tagged/28051) -- Teams channel: https://aka.ms/SwaggerSupport (for MS FTEs) -- Email: vscswagger@microsoft.com. +If you have any question or need support, reach out via +[aka.ms/azsdk/support](https://aka.ms/azsdk/support) (Microsoft-internal only) diff --git a/documentation/samplefiles-dp/ABOUT.md b/documentation/samplefiles-dp/ABOUT.md index 3c6e67ce94c9..25d934242479 100644 --- a/documentation/samplefiles-dp/ABOUT.md +++ b/documentation/samplefiles-dp/ABOUT.md @@ -1,9 +1,9 @@ +# About `samplefiles-dp` + This `samplefiles-dp` directory contains sample AutoRest configuration files for data-plane specs: `README.md`. -It also contains the sample hand-written OpenAPI specification files referenced by these files. - -You can learn more about AutoRest configuration files at -[aka.ms/azsdk/autorest](https://aka.ms/azsdk/autorest). +It also contains the sample hand-written OpenAPI specification files referenced +by the README files. > [!CAUTION] > The example OpenAPI specification files in this directory are hand-written, @@ -19,6 +19,12 @@ see [dataplane samples for multi client](samplefiles-dp-for-multi-client). This is an advanced scenario. You can learn more about it at [aka.ms/azsdk/spec-dirs#advanced-scenario-service-group](https://aka.ms/azsdk/spec-dirs#advanced-scenario-service-group). +You can learn more about AutoRest configuration files at +[aka.ms/azsdk/autorest](https://aka.ms/azsdk/autorest). + +You can learn more about the overall directory structure at +[aka.ms/azsdk/spec-dirs](https://aka.ms/azsdk/spec-dirs). + See also: [../samplefiles](../samplefiles) diff --git a/documentation/samplefiles/ABOUT.md b/documentation/samplefiles/ABOUT.md index e1ffa28110b6..790793399d57 100644 --- a/documentation/samplefiles/ABOUT.md +++ b/documentation/samplefiles/ABOUT.md @@ -1,16 +1,21 @@ +# About `samplefiles` + This `samplefiles` directory contains sample AutoRest configuration files: `README.*.md`. It also contains the sample hand-written OpenAPI -specification files referenced by these files. +specification files referenced by the README files. + +> [!CAUTION] +> The example OpenAPI specification files in this directory are hand-written, +> which is a legacy, obsolete approach. For current approach refer to +> [aka.ms/azsdk/typespec](https://aka.ms/azsdk/typespec). Finally, the `./Microsoft.YourServiceName/stable/YYYY-MM-DD/scenarios/quickStart.yaml` -is an [api-scenario](../api-scenario) sample. +is an [`api-scenario`](../api-scenario/README.md) sample. You can learn more about AutoRest configuration files at [aka.ms/azsdk/autorest](https://aka.ms/azsdk/autorest). -> [!CAUTION] -> The example OpenAPI specification files in this directory are hand-written, -> which is a legacy, obsolete approach. For current approach refer to -> [aka.ms/azsdk/typespec](https://aka.ms/azsdk/typespec). +You can learn more about the overall directory structure at +[aka.ms/azsdk/spec-dirs](https://aka.ms/azsdk/spec-dirs). See also: [../samplefiles-dp](../samplefiles-dp) From 625767d6b1678e7f8b62880bee3446bb94137c26 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Mon, 15 Apr 2024 16:11:46 -0700 Subject: [PATCH 4/6] ongoing --- documentation/api-scenario/{readme.md => readmex.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename documentation/api-scenario/{readme.md => readmex.md} (100%) diff --git a/documentation/api-scenario/readme.md b/documentation/api-scenario/readmex.md similarity index 100% rename from documentation/api-scenario/readme.md rename to documentation/api-scenario/readmex.md From 5b99bb6503da41b3ccdb5ae59611b09fc57d420c Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Mon, 15 Apr 2024 16:11:58 -0700 Subject: [PATCH 5/6] ongoing --- documentation/api-scenario/{readmex.md => README.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename documentation/api-scenario/{readmex.md => README.md} (100%) diff --git a/documentation/api-scenario/readmex.md b/documentation/api-scenario/README.md similarity index 100% rename from documentation/api-scenario/readmex.md rename to documentation/api-scenario/README.md From 1422a9fbb791cd0d24e3c3e4e1ff6586a021acd1 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Mon, 15 Apr 2024 16:13:56 -0700 Subject: [PATCH 6/6] better links --- documentation/samplefiles-dp/ABOUT.md | 2 +- documentation/samplefiles/ABOUT.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/samplefiles-dp/ABOUT.md b/documentation/samplefiles-dp/ABOUT.md index 25d934242479..a9499c69c9f1 100644 --- a/documentation/samplefiles-dp/ABOUT.md +++ b/documentation/samplefiles-dp/ABOUT.md @@ -25,6 +25,6 @@ You can learn more about AutoRest configuration files at You can learn more about the overall directory structure at [aka.ms/azsdk/spec-dirs](https://aka.ms/azsdk/spec-dirs). -See also: [../samplefiles](../samplefiles) +See also: [`samplefiles`](../samplefiles/ABOUT.md) diff --git a/documentation/samplefiles/ABOUT.md b/documentation/samplefiles/ABOUT.md index 790793399d57..09978fd29bfc 100644 --- a/documentation/samplefiles/ABOUT.md +++ b/documentation/samplefiles/ABOUT.md @@ -18,4 +18,4 @@ You can learn more about AutoRest configuration files at You can learn more about the overall directory structure at [aka.ms/azsdk/spec-dirs](https://aka.ms/azsdk/spec-dirs). -See also: [../samplefiles-dp](../samplefiles-dp) +See also: [`samplefiles-dp`](../samplefiles-dp/ABOUT.md)