Add the missing description to summarization parameter #20809

wangyuantao · 2022-09-21T21:21:58Z

Data Plane API - Pull Request

API Info: The Basics

Most of the information about your service should be captured in the issue that serves as your engagement record.

Link to engagement record issue:

Is this review for (select one):

a private preview
a public preview
GA release

Change Scope

^{This section will help us focus on the specific parts of your API that are new or have been modified.
Please share a link to the design document for the new APIs, a link to the previous Open API document (swagger) if applicable, and the root paths that have been updated.}

Design Document:
Previous Open API Doc:
Updated paths:

❔Got questions? Need additional info?? We are here to help!

Contact us!

The Azure API Review Board is dedicated to helping you create amazing APIs. You can read about our mission and learn more about our process on our wiki.

💬 Teams Channel
💌 email

Click here for links to tools, specs, guidelines & other good stuff

Tooling

Open API validation tools were run on this PR. Go here to see how to fix errors
Spectral Linting
Open API Hub

Guidelines & Specifications

Helpful Links

Azure DevTools Wiki

openapi-pipeline-app · 2022-09-21T21:22:02Z

Swagger Validation Report

️❌BreakingChange: 2 Errors, 0 Warnings failed [Detail]

Rule	Message
`❌` Runtime Exception	"new":"https://github.com/Azure/azure-rest-api-specs/blob/f5c0456ac16dbf7c3c1ce3e9f4b332a36e8bd1a5/dev/cognitiveservices/data-plane/Language", "old":"https://github.com/Azure/azure-rest-api-specs/blob/main//mnt/vss/_work/1/same-version-c93b354fd9c14905bb574a8834c4d69b/dev/cognitiveservices/data-plane/Language", "details":"Command failed: node /mnt/vss/_work/_tasks/AzureApiValidation_5654d05d-82c1-48da-ad8f-161b817f6d41/0.0.42/common/temp/node_modules/.pnpm/@Azure [email protected]/node_modules/autorest/dist/app.js /tmp/readme.oad.old.md --v2 --tag=oad-default-tag --output-artifact=swagger-document.json --output-artifact=swagger-document.map --output-file=old --output-folder=/tmp\nFATAL: swagger-document/compose - FAILED\nFATAL: Error: '$["x-ms-parameterized-host"].hostTemplate' has incompatible values (---\n'Endpoint/language'\n, ---\n'Endpoint/language/authoring'\n).\n Error: '$["x-ms-parameterized-host"].hostTemplate' has incompatible values (---\n'Endpoint/language'\n, ---\n'Endpoint/language/authoring'\n).\n"
`❌` BreakingChangeToolException	"details":""errno":-21, "syscall":"read", "code":"EISDIR""

️️✔️Breaking Change(Cross-Version) succeeded [Detail] [Expand]

There are no breaking changes.

️️✔️CredScan succeeded [Detail] [Expand]

There is no credential detected.

️❌LintDiff: 2 Errors, 0 Warnings failed [Detail]

[must fix]The following errors/warnings are introduced by current PR:

Rule	Message	Related RPC [For API reviewers]
`❌` AutoRest exception	"location":"dev/cognitiveservices/data-plane/Language/readme.md", "tag":"release_2022-07-01-preview", "details":"swagger-document/compose - FAILED"
`❌` AutoRest exception	"location":"dev/cognitiveservices/data-plane/Language/readme.md", "tag":"release_2022-07-01-preview", "details":"Error: '$["x-ms-parameterized-host"].hostTemplate' has incompatible values (---'Endpoint/language', ---'Endpoint/language/authoring')."

The following errors/warnings exist before current PR submission:

Rule	Message
⚠️ R2010 - LongRunningOperationsOptionsValidator	A LRO Post operation with return schema must have 'x-ms-long-running-operation-options' extension enabled. Location: cognitiveservices/data-plane/Language/questionanswering-authoring.json#L263

️️✔️Avocado succeeded [Detail] [Expand]

Validation passes for Avocado.

️️✔️ApiReadinessCheck succeeded [Detail] [Expand]

️️✔️~[Staging] ServiceAPIReadinessTest succeeded [Detail] [Expand]

Validation passes for ServiceAPIReadinessTest.

️️✔️~[Staging] TrafficValidation succeeded [Detail] [Expand]

️️✔️ModelValidation succeeded [Detail] [Expand]

Validation passes for ModelValidation.

️️✔️SemanticValidation succeeded [Detail] [Expand]

Validation passes for SemanticValidation.

️️✔️PoliCheck succeeded [Detail] [Expand]

Validation passed for PoliCheck.

️️✔️SDK Track2 Validation succeeded [Detail] [Expand]

Validation passes for SDKTrack2Validation

️️✔️PrettierCheck succeeded [Detail] [Expand]

Validation passes for PrettierCheck.

️️✔️SpellCheck succeeded [Detail] [Expand]

Validation passes for SpellCheck.

️️✔️Lint(RPaaS) succeeded [Detail] [Expand]

Validation passes for Lint(RPaaS).

️️✔️CadlValidation succeeded [Detail] [Expand]

Validation passes for CadlValidation.

️️✔️PR Summary succeeded [Detail] [Expand]

Validation passes for Summary.

_{Posted by Swagger Pipeline | How to fix these errors?}

openapi-workflow-bot · 2022-09-21T21:22:02Z

Hi, @wangyuantao Thanks for your PR. I am workflow bot for review process. Here are some small tips.

Please ensure to do self-check against checklists in first PR comment.

PR assignee is the person auto-assigned and responsible for your current PR reviewing and merging.

For specs comparison cross API versions, Use API Specs Comparison Report Generator

If there is CI failure(s), to fix CI error(s) is mandatory for PR merging; or you need to provide justification in PR comment for explanation. How to fix?

Any feedback about review process or workflow bot, pls contact swagger and tools team. [email protected]

openapi-pipeline-app · 2022-09-21T21:22:02Z

Swagger Generation Artifacts

️️✔️ApiDocPreview succeeded [Detail] [Expand]

️️✔️SDK Breaking Change Tracking succeeded [Detail] [Expand]

Breaking Changes Tracking

️⚠️ azure-sdk-for-net-track2 warning [Detail]

⚠️Warning [Logs]Release - Generate from dad16c7. SDK Automation 14.0.0

command	pwsh ./eng/scripts/Automation-Sdk-Init.ps1 ../azure-sdk-for-net_tmp/initInput.json ../azure-sdk-for-net_tmp/initOutput.json
warn	File azure-sdk-for-net_tmp/initOutput.json not found to read
command	pwsh ./eng/scripts/Invoke-GenerateAndBuildV2.ps1 ../azure-sdk-for-net_tmp/generateInput.json ../azure-sdk-for-net_tmp/generateOutput.json
warn	No file changes detected after generation
warn	Skip detect changed packages

️⚠️ azure-sdk-for-python warning [Detail]

⚠️Warning [Logs]Release - Generate from dad16c7. SDK Automation 14.0.0

command	sh scripts/automation_init.sh ../azure-sdk-for-python_tmp/initInput.json ../azure-sdk-for-python_tmp/initOutput.json
cmderr	[automation_init.sh] WARNING: Skipping azure-nspkg as it is not installed.
command	sh scripts/automation_generate.sh ../azure-sdk-for-python_tmp/generateInput.json ../azure-sdk-for-python_tmp/generateOutput.json
cmderr	[automation_generate.sh]
cmderr	[automation_generate.sh] npm notice New minor version of npm available! 8.15.0 -> 8.19.2
cmderr	[automation_generate.sh] npm notice Changelog: <https://github.com/npm/cli/releases/tag/v8.19.2>
cmderr	[automation_generate.sh] npm notice Run `npm install -g [email protected]` to update!
cmderr	[automation_generate.sh] npm notice
warn	No file changes detected after generation
warn	No package detected after generation

_{Posted by Swagger Pipeline | How to fix these errors?}

openapi-pipeline-app · 2022-09-21T21:22:03Z

Swagger pipeline restarted successfully. If there is ApiView generated, it will be updated in this comment.

openapi-workflow-bot · 2022-09-21T21:25:52Z

Hi @wangyuantao, Your PR has some issues. Please fix the CI sequentially by following the order of Avocado, semantic validation, model validation, breaking change, lintDiff. If you have any questions, please post your questions in this channel https://aka.ms/swaggersupport.

Task	How to fix	Priority
Avocado	Fix-Avocado	High
Semantic validation	Fix-SemanticValidation-Error	High
Model validation	Fix-ModelValidation-Error	High
LintDiff	Fix-LintDiff	high

If you need further help, please feedback via swagger feedback.

dev/cognitiveservices/data-plane/Language/common.json

wangyuantao · 2022-09-28T15:36:49Z

Are these really for 2022-10-01-preview as well? Please note that a PR was already created to publish: #20810
Though, @kayousef, that shouldn't be targeting main but a new release branch that everyone can target. While they could technically target your PR branch, validation won't run. This is described in the internal documentation for publishing (both the old and new ways i.e. the dev/ folder).

Is this the right branch name? #20913

@yuantao-wang @heaths I'm not sure I follow what is the difference between #20810 and #20913

I'm also very confused what we should do from here.

heaths · 2022-09-28T22:47:25Z

@lmazuel can you merge this? The error is still saying security has duplicate incompatible definitions but the error shows two definitions that are obviously the same. This is breaking the BreakingChange validation as well, but there's no other errors (though, perhaps this is a blocker and there are some).

sush2218 · 2022-09-29T03:23:13Z

dev/cognitiveservices/data-plane/Language/questionanswering-authoring.json

@@ -32,7 +32,7 @@
    }
  ],
  "x-ms-parameterized-host": {
-    "hostTemplate": "{Endpoint}/language/authoring",


Can we know the reason for this change ?

It causes validation error. Let me revert this, and request exception.

Standalone fix for this: #20927

into lc

wangyuantao · 2022-09-29T06:43:04Z

dev/cognitiveservices/data-plane/Language/common.json

      "description": "Supported Cognitive Services endpoint (e.g., https://<resource-name>.api.cognitiveservices.azure.com).",
      "x-ms-parameter-location": "client",
      "required": true,
      "type": "string",
-      "format": "uri",


This is to make consistent with July preview. Is that OK? @heaths

For anything new, I recommend declaring the uri format. The others should've been before, but it's consider a breaking change to do it after. Most languages will ignore it anyway and just do a string, but some lanugages - like C# - actually end up using a Uri class (correctly). If you don't, we'll have to transform it and we're trying to avoid that. The swaggers should be the main source of truth. They are the spec, afterall. :)

@heaths there are so many conflict rules and I'm confused which rule trump which rule... This is existing stuff, not new. In /specification folder, the latest stable version and the latest preview has no format, only /dev folder has format uri. Given we cannot break anything GA, we should fix /dev folder as what I'm doing here - remove format uri, right?

sush2218 · 2022-09-29T06:48:20Z

dev/cognitiveservices/data-plane/Language/questionanswering-authoring.json

@@ -285,12 +285,6 @@
          "application/json"
        ],
        "responses": {
-          "200": {
-            "description": "Export job status, project metadata, and assets.",


200 response is needed for SDK. Heath have added this in our earlier swaggers. There will be a validation error but that can be overriden.

Reverted. How to override this specific validation error?

Fixed in example.

wangyuantao · 2022-09-30T00:44:27Z

dev/cognitiveservices/data-plane/Language/common.json

@@ -1540,12 +1538,11 @@
  },
  "parameters": {
    "Endpoint": {
-      "name": "Endpoint",
+      "name": "endpoint",


In /specification folder, the latest stable is uppercase "Endpoint", and latest preview is lowercase "endpoint", so no matter what we do here, it is a breaking change. So I will revert this to keep it in uppercase "Endpoint" so no breaking change to GA version. @heaths, Is that OK?

into lc

wangyuantao · 2022-09-30T01:27:25Z

...ta-plane/Language/examples/questionanswering/authoring/SuccessfulProjectSubmitExportJob.json

@@ -13,6 +13,18 @@
    }
  },
  "responses": {
+    "200": {


I fix the validation error by adding 200 into the example responses. Let me know if that is OK with you. @heaths , @sush2218

add the missing description

f574803

wangyuantao requested review from annatisch, heaths, deyaaeldeen, kristapratico, mssfang and a team as code owners September 21, 2022 21:21

wangyuantao requested review from tg-msft and mikekistler and removed request for a team September 21, 2022 21:22

openapi-assignment-bot bot assigned chunyu3 Sep 21, 2022

ghost added the Cognitive Services label Sep 21, 2022

openapi-pipeline-app bot added the CI-FixRequiredOnFailure label Sep 21, 2022

kristapratico approved these changes Sep 21, 2022

View reviewed changes

deyaaeldeen reviewed Sep 21, 2022

View reviewed changes

dev/cognitiveservices/data-plane/Language/common.json Outdated Show resolved Hide resolved

fix wording

4728032

deyaaeldeen approved these changes Sep 21, 2022

View reviewed changes

wangyuantao and others added 8 commits September 23, 2022 08:53

Merge branch 'Azure:main' into lc

192c15a

fix prettier

cd02418

remove endpoint format uri

40e6bbe

fix lintdiff

0c6ad62

add format uri back

6b8a0ee

x-ms-parameterized-host hostTemplate consistent

a438b31

fix prettier

d092460

fix typo

3732811

fix more validation errors

69ef8da

jianyexi added the Approved-LintDiff label Sep 29, 2022

wangyuantao added Approved-BreakingChange DO NOT USE! OBSOLETE label. See https://github.com/Azure/azure-sdk-tools/issues/6374 and removed Approved-BreakingChange DO NOT USE! OBSOLETE label. See https://github.com/Azure/azure-sdk-tools/issues/6374 labels Sep 29, 2022

sush2218 reviewed Sep 29, 2022

View reviewed changes

yuantao-wang and others added 6 commits September 28, 2022 21:56

revert authoring

a486385

Merge branch 'lc' of https://github.com/wangyuantao/azure-rest-api-specs

aecabc0

into lc

Merge branch 'main' into lc

055183a

fix authoring

1da2ccb

Merge branch 'lc' of https://github.com/wangyuantao/azure-rest-api-specs

545d4ae

into lc

fix authoring

cfd67f7

wangyuantao commented Sep 29, 2022

View reviewed changes

sush2218 reviewed Sep 29, 2022

View reviewed changes

add 200 back to export qna authoring

44df77f

wangyuantao commented Sep 30, 2022

View reviewed changes

yuantao-wang and others added 4 commits September 29, 2022 17:49

revert endpoint to Endpoint

4d69d00

Merge branch 'Azure:main' into lc

dd79fb5

fix example of qna authoring

a6ad551

Merge branch 'lc' of https://github.com/wangyuantao/azure-rest-api-specs

48e305d

into lc

AzureRestAPISpecReview added the data-plane label Sep 30, 2022

yuantao-wang added 2 commits September 29, 2022 18:16

prettier revert

875df36

fix api version

c9f050c

wangyuantao commented Sep 30, 2022

View reviewed changes

revert authoring

f5c0456

wangyuantao requested a review from sush2218 September 30, 2022 03:13

wangyuantao added the Approved-BreakingChange DO NOT USE! OBSOLETE label. See https://github.com/Azure/azure-sdk-tools/issues/6374 label Sep 30, 2022

chunyu3 merged commit dad16c7 into Azure:main Sep 30, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add the missing description to summarization parameter #20809

Add the missing description to summarization parameter #20809

wangyuantao commented Sep 21, 2022 •

edited by openapi-workflow-bot bot

Loading

openapi-pipeline-app bot commented Sep 21, 2022 •

edited

Loading

openapi-workflow-bot bot commented Sep 21, 2022

openapi-pipeline-app bot commented Sep 21, 2022 •

edited

Loading

Breaking Changes Tracking

openapi-pipeline-app bot commented Sep 21, 2022 •

edited

Loading

openapi-workflow-bot bot commented Sep 21, 2022

wangyuantao commented Sep 28, 2022

heaths commented Sep 28, 2022

sush2218 Sep 29, 2022

wangyuantao Sep 29, 2022

wangyuantao Sep 29, 2022

wangyuantao Sep 29, 2022

heaths Sep 29, 2022

wangyuantao Sep 30, 2022

sush2218 Sep 29, 2022

wangyuantao Sep 29, 2022

wangyuantao Sep 30, 2022

wangyuantao Sep 30, 2022

wangyuantao Sep 30, 2022

Add the missing description to summarization parameter #20809

Add the missing description to summarization parameter #20809

Conversation

wangyuantao commented Sep 21, 2022 • edited by openapi-workflow-bot bot Loading

Data Plane API - Pull Request

API Info: The Basics

Change Scope

❔Got questions? Need additional info?? We are here to help!

Tooling

Guidelines & Specifications

Helpful Links

openapi-pipeline-app bot commented Sep 21, 2022 • edited Loading

Swagger Validation Report

openapi-workflow-bot bot commented Sep 21, 2022

openapi-pipeline-app bot commented Sep 21, 2022 • edited Loading

Swagger Generation Artifacts

Breaking Changes Tracking

openapi-pipeline-app bot commented Sep 21, 2022 • edited Loading

openapi-workflow-bot bot commented Sep 21, 2022

wangyuantao commented Sep 28, 2022

heaths commented Sep 28, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wangyuantao commented Sep 21, 2022 •

edited by openapi-workflow-bot bot

Loading

openapi-pipeline-app bot commented Sep 21, 2022 •

edited

Loading

openapi-pipeline-app bot commented Sep 21, 2022 •

edited

Loading

openapi-pipeline-app bot commented Sep 21, 2022 •

edited

Loading