[AQ] edit pass: REST API reference docs by ShawnJackson · Pull Request #23288 · Azure/azure-rest-api-specs

ShawnJackson · 2023-03-24T22:12:23Z

@mikekistler, @nitinme - Here's my edit pass on the five JSON files, as requested in work item 69663. Please review my changes and let me know if any of them affect technical meaning.

openapi-workflow-bot · 2023-03-24T22:12:27Z

Hi, @ShawnJackson 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. vscswagger@microsoft.com

openapi-pipeline-app · 2023-03-24T22:12:29Z

Swagger Validation Report

️️✔️BreakingChange succeeded [Detail] [Expand]

There are no breaking changes.

compared swaggers (via Oad v0.10.4)]	new version	base version
ContentModerator.json	v1.0(c747f66)	v1.0(main)
analyzeconversations.json	2022-10-01-preview(c747f66)	2022-10-01-preview(main)
questionanswering.json	2022-10-01-preview(c747f66)	2022-10-01-preview(main)
TextAnalytics.json	v3.2-preview.2(c747f66)	v3.2-preview.2(main)

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

There are no breaking changes.

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

There is no credential detected.

️⚠️LintDiff: 0 Warnings warning [Detail]

compared tags (via openapi-validator v2.0.0)	new version	base version
release_1_0	release_1_0(c747f66)	release_1_0(main)
release_2022_10_01_preview	release_2022_10_01_preview(c747f66)	release_2022_10_01_preview(main)
release_3_2_preview.2	release_3_2_preview.2(c747f66)	release_3_2_preview.2(main)

The following errors/warnings exist before current PR submission:

Only 30 items are listed, please refer to log for more details.

Rule	Message
`❌` HostParametersValidation	The host parameter must be called 'endpoint'. Location: ContentModerator/stable/v1.0/ContentModerator.json#L24
`❌` HostParametersValidation	The host parameter must be typed 'type 'string', format 'url''. Location: ContentModerator/stable/v1.0/ContentModerator.json#L24
`❌` XmsEnumValidation	The enum types should have x-ms-enum type extension set with appropriate options. Location: ContentModerator/stable/v1.0/ContentModerator.json#L219
`❌` XmsEnumValidation	The enum types should have x-ms-enum type extension set with appropriate options. Location: ContentModerator/stable/v1.0/ContentModerator.json#L275
`❌` IntegerTypeMustHaveFormat	The integer type does not have a format, please add it. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1043
`❌` IntegerTypeMustHaveFormat	The integer type does not have a format, please add it. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1050
`❌` OperationIdNounVerb	Per the Noun_Verb convention for Operation Ids, the noun 'Reviews' should not appear after the underscore. Note: If you have already shipped an SDK on top of this spec, fixing this warning may introduce a breaking change. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1124
`❌` OperationIdNounVerb	Per the Noun_Verb convention for Operation Ids, the noun 'Reviews' should not appear after the underscore. Note: If you have already shipped an SDK on top of this spec, fixing this warning may introduce a breaking change. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1218
`❌` XmsEnumValidation	The enum types should have x-ms-enum type extension set with appropriate options. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1251
`❌` XmsEnumValidation	The enum types should have x-ms-enum type extension set with appropriate options. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1347
`❌` AvoidAnonymousParameter	Inline/anonymous models must not be used, instead define a schema with a model name in the 'definitions' section and refer to it. This allows operations to share the models. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1364
`❌` IntegerTypeMustHaveFormat	The integer type does not have a format, please add it. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1428
`❌` IntegerTypeMustHaveFormat	The integer type does not have a format, please add it. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1468
`❌` IntegerTypeMustHaveFormat	The integer type does not have a format, please add it. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1474
`❌` OperationIdNounVerb	Per the Noun_Verb convention for Operation Ids, the noun 'Reviews' should not appear after the underscore. Note: If you have already shipped an SDK on top of this spec, fixing this warning may introduce a breaking change. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1519
`❌` XmsEnumValidation	The enum types should have x-ms-enum type extension set with appropriate options. Location: ContentModerator/stable/v1.0/ContentModerator.json#L1617
`❌` OperationIdNounVerb	Per the Noun_Verb convention for Operation Ids, the noun 'Reviews' should not appear after the underscore. Note: If you have already shipped an SDK on top of this spec, fixing this warning may introduce a breaking change. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2143
`❌` IntegerTypeMustHaveFormat	The integer type does not have a format, please add it. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2271
`❌` MissingTypeObject	The schema 'Frames' is considered an object but without a 'type:object', please add the missing 'type:object'. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2314
`❌` MissingTypeObject	The schema 'Frame' is considered an object but without a 'type:object', please add the missing 'type:object'. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2329
`❌` MissingTypeObject	The schema 'Screen' is considered an object but without a 'type:object', please add the missing 'type:object'. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2356
`❌` MissingTypeObject	The schema 'Classification' is considered an object but without a 'type:object', please add the missing 'type:object'. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2406
`❌` MissingTypeObject	The schema 'Category1' is considered an object but without a 'type:object', please add the missing 'type:object'. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2409
`❌` MissingTypeObject	The schema 'Category2' is considered an object but without a 'type:object', please add the missing 'type:object'. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2418
`❌` MissingTypeObject	The schema 'Category3' is considered an object but without a 'type:object', please add the missing 'type:object'. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2427
`❌` MissingTypeObject	The schema 'PII' is considered an object but without a 'type:object', please add the missing 'type:object'. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2442
`❌` MissingTypeObject	The schema 'Email' is considered an object but without a 'type:object', please add the missing 'type:object'. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2477
`❌` IntegerTypeMustHaveFormat	The integer type does not have a format, please add it. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2492
`❌` MissingTypeObject	The schema 'SSN' is considered an object but without a 'type:object', please add the missing 'type:object'. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2498
`❌` IntegerTypeMustHaveFormat	The integer type does not have a format, please add it. Location: ContentModerator/stable/v1.0/ContentModerator.json#L2505

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

Validation passes for Avocado.

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

️⚠️~[Staging] ServiceAPIReadinessTest: 0 Warnings warning [Detail]

API Test is not triggered due to precheck failure. Check pipeline log for details.

️️✔️SwaggerAPIView succeeded [Detail] [Expand]

️️✔️CadlAPIView succeeded [Detail] [Expand]

️️✔️TypeSpecAPIView succeeded [Detail] [Expand]

️❌ModelValidation: 15 Errors, 0 Warnings failed [Detail]

Rule	Message
`❌` XMS_EXAMPLE_NOTFOUND_ERROR	x-ms-example not found in ImageModeration_FindFaces. Url: ContentModerator/stable/v1.0/ContentModerator.json#L31:15
`❌` XMS_EXAMPLE_NOTFOUND_ERROR	x-ms-example not found in ImageModeration_OCR. Url: ContentModerator/stable/v1.0/ContentModerator.json#L70:15
`❌` XMS_EXAMPLE_NOTFOUND_ERROR	x-ms-example not found in ImageModeration_Evaluate. Url: ContentModerator/stable/v1.0/ContentModerator.json#L115:15
`❌` XMS_EXAMPLE_NOTFOUND_ERROR	x-ms-example not found in ImageModeration_Match. Url: ContentModerator/stable/v1.0/ContentModerator.json#L154:15
`❌` XMS_EXAMPLE_NOTFOUND_ERROR	x-ms-example not found in Reviews_AddVideoFrame. Url: ContentModerator/stable/v1.0/ContentModerator.json#L1411:15
`❌` XMS_EXAMPLE_NOTFOUND_ERROR	x-ms-example not found in ImageModeration_FindFacesFileInput. Url: ContentModerator/stable/v1.0/ContentModerator.json#L1659:15
`❌` XMS_EXAMPLE_NOTFOUND_ERROR	x-ms-example not found in ImageModeration_OCRFileInput. Url: ContentModerator/stable/v1.0/ContentModerator.json#L1804:15
`❌` XMS_EXAMPLE_NOTFOUND_ERROR	x-ms-example not found in ImageModeration_EvaluateFileInput. Url: ContentModerator/stable/v1.0/ContentModerator.json#L1851:15
`❌` XMS_EXAMPLE_NOTFOUND_ERROR	x-ms-example not found in ImageModeration_MatchFileInput. Url: ContentModerator/stable/v1.0/ContentModerator.json#L1993:15
`❌` XMS_EXAMPLE_NOTFOUND_ERROR	x-ms-example not found in ListManagementImage_AddImageFileInput. Url: ContentModerator/stable/v1.0/ContentModerator.json#L2092:15
`❌` INVALID_TYPE	Expected type integer but found type string Url: ContentModerator/stable/v1.0/ContentModerator.json#L3483:32 ExampleUrl: stable/v1.0/examples/CreateVideoReviewResource.JSON#L8:31
`❌` ENUM_CASE_MISMATCH	Enum does not match case for: UnPublished Url: ContentModerator/stable/v1.0/ContentModerator.json#L3571:23 ExampleUrl: stable/v1.0/examples/CreateVideoReviewResource.JSON#L8:31
`❌` XMS_EXAMPLE_NOTFOUND_ERROR	x-ms-example not found in Reviews_AddVideoFrameStream. Url: ContentModerator/stable/v1.0/ContentModerator.json#L2243:15
`❌` INVALID_FORMAT	Object didn't pass validation for format uuid: {Job ID} Url: TextAnalytics/preview/v3.2-preview.2/TextAnalytics.json#L3415:14 ExampleUrl: preview/v3.2-preview.2/examples/SuccessfulHealthStatusRequest.json#L6:14
`❌` INVALID_FORMAT	Object didn't pass validation for format uuid: {Job ID} Url: TextAnalytics/preview/v3.2-preview.2/TextAnalytics.json#L3415:14 ExampleUrl: preview/v3.2-preview.2/examples/SuccessfulHealthDeleteRequest.json#L6:14

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

Validation passes for SemanticValidation.

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

Validation passed for PoliCheck.

️️✔️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.

️️✔️TypeSpec Validation succeeded [Detail] [Expand]

Validation passes for TypeSpec Validation.

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

Validation passes for Summary.

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

openapi-pipeline-app · 2023-03-24T22:12:30Z

Swagger Generation Artifacts

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

 Please click here to preview with your @microsoft account.

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

Breaking Changes Tracking

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

⚠️Warning [Logs]Release - Generate from 7e53713. 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		specification/cognitiveservices/data-plane/ContentModerator/readme.md skipped due to azure-sdk-for-net-track2 not found in swagger-to-sdk
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

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

openapi-pipeline-app · 2023-03-24T22:12:31Z

Generated ApiView

Language	Package Name	ApiView Link
Swagger	cognitiveservices-data-plane-TextAnalytics	https://apiview.dev/Assemblies/Review/a60d598bc97e4b7196412ef2a071d94b

openapi-workflow-bot · 2023-03-24T22:21:38Z

Hi @ShawnJackson, 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.

mikekistler

This looks really good!

I left some comments about "optional" and "required" in descriptions and also repeating lists of allowed values. Please apply this throughout.

Tag me to re-review when those changes are done and this should be good to merge.

specification/cognitiveservices/data-plane/AnomalyDetector/stable/v1.1/openapi.json

ShawnJackson · 2023-03-27T18:20:14Z

@mikekistler - I applied your suggestions globally. Please take another look.

heaths

A random sampling of text LGTM.

heaths · 2023-03-27T21:53:51Z

Be sure to go through the PoliCheck and SpellCheck failures.

The ModelValidation failures are moot since you're not changing anything besides descrptions.

For Anomaly Detector, please update the .cadl file(s) and regenerate the swagger instead of the swagger directly.

mikekistler

Looks good! 👍

There is one complication with the specification/cognitiveservices/data-plane/AnomalyDetector/stable/v1.1/openapi.json. This file is actually generated using TypeSpec, so we need to make the corresponding changes to the TypeSpec source. I can do that but I'd like to separate that into it's own PR. Can you please drop that file from this PR? I'll create a new PR to include the updated TypeSpec and your changed openapi.json.

ShawnJackson · 2023-03-30T15:31:44Z

Looks good! 👍

There is one complication with the specification/cognitiveservices/data-plane/AnomalyDetector/stable/v1.1/openapi.json. This file is actually generated using TypeSpec, so we need to make the corresponding changes to the TypeSpec source. I can do that but I'd like to separate that into it's own PR. Can you please drop that file from this PR? I'll create a new PR to include the updated TypeSpec and your changed openapi.json.

@mikekistler - I dropped openapi.json from this PR.

heaths · 2023-03-30T23:29:08Z

The spell check issue was fixed in #23379 and the model validation issues weren't introduced here.

* edit pass: rest-api-reference-docs * edit pass: rest-api-reference-docs * edit pass: rest-api-reference-docs * removing file * blacklist to blocklist

ShawnJackson requested review from a team, annatisch, deyaaeldeen, heaths, joseharriaga, kristapratico, mssfang and yangyuan as code owners March 24, 2023 22:12

ShawnJackson requested review from bexxx and vicancy and removed request for a team March 24, 2023 22:12

openapi-assignment-bot bot assigned heaths Mar 24, 2023

ghost added the Cognitive Services label Mar 24, 2023

ghost added the Cognitive - Language label Mar 24, 2023

AzureRestAPISpecReview added Cadl Authored with Cadl CI-FixRequiredOnFailure data-plane labels Mar 24, 2023

mikekistler self-requested a review March 25, 2023 23:01

mikekistler reviewed Mar 26, 2023

View reviewed changes

heaths approved these changes Mar 27, 2023

View reviewed changes

mikekistler approved these changes Mar 30, 2023

View reviewed changes

mikekistler requested a review from nitinme March 30, 2023 14:04

heaths added the Approved-ModelValidation label Mar 30, 2023

ShawnJackson added 5 commits March 30, 2023 16:37

edit pass: rest-api-reference-docs

148f661

edit pass: rest-api-reference-docs

0267703

edit pass: rest-api-reference-docs

761c106

removing file

75f6e49

blacklist to blocklist

c747f66

heaths force-pushed the rest-api-reference-docs branch from fed6669 to c747f66 Compare March 30, 2023 23:38

heaths merged commit 7e53713 into Azure:main Mar 31, 2023

Conversation

ShawnJackson commented Mar 24, 2023

Uh oh!

openapi-workflow-bot bot commented Mar 24, 2023

Uh oh!

openapi-pipeline-app bot commented Mar 24, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Swagger Validation Report

Uh oh!

openapi-pipeline-app bot commented Mar 24, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Swagger Generation Artifacts

Breaking Changes Tracking

Uh oh!

openapi-pipeline-app bot commented Mar 24, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Generated ApiView

Uh oh!

openapi-workflow-bot bot commented Mar 24, 2023

Uh oh!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ShawnJackson commented Mar 27, 2023

Uh oh!

heaths left a comment

Choose a reason for hiding this comment

Uh oh!

heaths commented Mar 27, 2023

Uh oh!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

ShawnJackson commented Mar 30, 2023

Uh oh!

heaths commented Mar 30, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

openapi-pipeline-app bot commented Mar 24, 2023 •

edited

Loading

openapi-pipeline-app bot commented Mar 24, 2023 •

edited

Loading

openapi-pipeline-app bot commented Mar 24, 2023 •

edited

Loading