Add 6 lint rules feedback by ARM to the guideline #10125

jianyexi · 2020-07-14T05:07:58Z

MSFT employees can try out our new experience at OpenAPI Hub - one location for using our validation tools and finding your workflow.

Contribution checklist:

I commit to follow the Breaking Change Policy of “no breaking changes
I have reviewed the documentation for the workflow.
Validation tools were run on swagger spec(s) and errors have all been fixed in this PR. How to fix?

If any further question about AME onboarding or validation tools, please view the FAQ.

ARM API Review Checklist

Ensure to check this box if one of the following scenarios meet updates in the PR, so that label “WaitForARMFeedback” will be added automatically to involve ARM API Review. Failure to comply may result in delays for manifest application. Note this does not apply to data plane APIs, all “removals” and “adding a new property” no more require ARM API review.
- Adding new API(s)
- Adding a new API version
- Adding a new service
If you are blocked on ARM review and want to get the PR merged with urgency, please get the ARM oncall for reviews (RP Manifest Approvers team under Azure Resource Manager service) from IcM and reach out to them.

Breaking Change Review Checklist

If there are following updates in the PR, ensure to request an approval from API Review Board as defined in the Breaking Change Policy.

Removing API(s) in stable version
Removing properties in stable version
Removing API version(s) in stable version
Updating API in stable version with Breaking Change Validation errors
Updating API(s) in preview over 1 year

Please follow the link to find more details on PR review process.

openapi-pipeline-app · 2020-07-14T05:08:03Z

[Staging] Swagger Validation Report

️️✔️BreakingChange [Detail]

 There are no breaking changes.

️️✔️LintDiff [Detail]

 Validation passes for LintDiff.

️️✔️Avocado [Detail]

 Validation passes for Avocado.

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

azure-pipelines · 2020-07-14T05:08:14Z

Azure Pipelines successfully started running 1 pipeline(s).

openapi-sdkautomation · 2020-07-14T05:09:40Z

Azure CLI Extension Generation - Release

No readme.md specification configuration files were found that are associated with the files modified in this pull request, or swagger_to_sdk section in readme.md is not configured

openapi-sdkautomation · 2020-07-14T05:09:42Z

azure-sdk-for-go - Release

No readme.md specification configuration files were found that are associated with the files modified in this pull request, or swagger_to_sdk section in readme.md is not configured

openapi-sdkautomation · 2020-07-14T05:09:46Z

azure-sdk-for-java - Release

No readme.md specification configuration files were found that are associated with the files modified in this pull request, or swagger_to_sdk section in readme.md is not configured

openapi-sdkautomation · 2020-07-14T05:09:48Z

azure-sdk-for-js - Release

No readme.md specification configuration files were found that are associated with the files modified in this pull request, or swagger_to_sdk section in readme.md is not configured

openapi-sdkautomation · 2020-07-14T05:09:49Z

Trenton Generation - Release

No readme.md specification configuration files were found that are associated with the files modified in this pull request, or swagger_to_sdk section in readme.md is not configured

openapi-sdkautomation · 2020-07-14T05:09:52Z

azure-sdk-for-net - Release

No readme.md specification configuration files were found that are associated with the files modified in this pull request, or swagger_to_sdk section in readme.md is not configured

openapi-sdkautomation · 2020-07-14T05:09:52Z

azure-sdk-for-python - Release

No readme.md specification configuration files were found that are associated with the files modified in this pull request, or swagger_to_sdk section in readme.md is not configured

openapi-sdkautomation · 2020-07-14T05:09:56Z

azure-sdk-for-python-track2 - Release

No readme.md specification configuration files were found that are associated with the files modified in this pull request, or swagger_to_sdk section in readme.md is not configured

azuresdkci · 2020-07-14T05:47:40Z

Can one of the admins verify this patch?

azure-pipelines · 2020-07-14T07:12:20Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2020-07-14T07:26:55Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2020-07-14T07:30:14Z

Azure Pipelines successfully started running 1 pipeline(s).

pilor · 2020-07-14T17:06:40Z

documentation/openapi-authoring-automated-guidelines.md

+
+**Output Message** : The response in the GET collection operation "{0}" is different than the response definition in the individual GET operation "{1}".
+
+**Description** : For all resources (top-level and nested), collection GETs should have a response definition with a single property "value" containing an array of the "resource" schema.The definition returned in the collection "value" array should be the same as the response body for the individual GET.


response definition with a single property "value" [](start = 90, length = 50)

this isn't technically true, the definition should contain a "nextLink" property as well in most cases

thanks，I removed the word "single" to avoid the confusion

pilor

One minor comment

azure-pipelines · 2020-07-16T02:55:11Z

Azure Pipelines successfully started running 1 pipeline(s).

jianyexi · 2020-07-17T02:12:55Z

Can other reviewers take a look ?

jianyexi · 2020-07-20T03:08:33Z

@josefree could you review this PR ？

jianyexi · 2020-07-20T03:16:36Z

@ravbhatnagar @KrisBash @chiragg4u @majastrz Could you also review this PR to see if the rules match your requirement ? thanks

azure-pipelines · 2020-07-23T11:52:09Z

Azure Pipelines successfully started running 1 pipeline(s).

akning-ms · 2020-07-23T13:08:11Z

documentation/openapi-authoring-automated-guidelines.md

+
+### <a name="r4014" ></a>R4014 AllResourcesMustHaveGetOperation
+
+**Category** : ARM Warning


As this Rule is mainly to detect resource model which don't have path/get operation. As it is hard to know whether it is a really resource type from model, so we put it a warning first. @ ARM to confirm

What do you want me to confirm? If there is a PUT or a LIST on a URI there should be an equivalent GET for individual resources at that same path (i.e. GET on the PUT's URI, or GET on the LIST + {name} URI). This doesn't seem like it should be driven off the definitions, it should be driven off the paths in the spec.

Thanks @pilor, yes we want to confirm the approach to distinguish resourceType in path. your idea looks good.
but Is there any exception? e.g. /operations. if no ideal solution, we may put this rule as warn, not error initially

/operations and /skus should be the only legitimate exceptions, good call on that. I'm sure there are plenty of places where RPs have done this but it should be something that requires a suppression in order to use since it goes against the RPC. Is there a way to run the rule against all existing specs to see what the current problem space is?

Actually we already scan the whole specs, and over 300 violations of this rule, a lot of them only have list model operation and no put operation and point get operation , so it's hard to say that these models are ARM resource, as they can be some kinds of operations' result

ravbhatnagar · 2020-07-27T20:26:38Z

documentation/openapi-authoring-automated-guidelines.md

@@ -56,6 +56,11 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
 | [R4007](#r4007) | [DefaultErrorResponseSchema](#r4007) | ARM OpenAPI(swagger) specs |
 | [R4010](#r4010) | [RequiredDefaultResponse](#r4010) | ARM OpenAPI(swagger) specs |
 | [R4011](#r4011) | [DeleteOperationResponses](#r4011) | ARM OpenAPI(swagger) specs |
+| [R4015](#r4015) | [NestedResourcesMustHaveListOperation](#r4015) | ARM OpenAPI(swagger) specs |
+| [R4016](#r4016) | [TopLevelResourcesListByResourceGroup](#r4016) | ARM OpenAPI(swagger) specs |


this, i believe, is already automated.

ravbhatnagar · 2020-07-27T20:26:51Z

documentation/openapi-authoring-automated-guidelines.md

@@ -56,6 +56,11 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
 | [R4007](#r4007) | [DefaultErrorResponseSchema](#r4007) | ARM OpenAPI(swagger) specs |
 | [R4010](#r4010) | [RequiredDefaultResponse](#r4010) | ARM OpenAPI(swagger) specs |
 | [R4011](#r4011) | [DeleteOperationResponses](#r4011) | ARM OpenAPI(swagger) specs |
+| [R4015](#r4015) | [NestedResourcesMustHaveListOperation](#r4015) | ARM OpenAPI(swagger) specs |
+| [R4016](#r4016) | [TopLevelResourcesListByResourceGroup](#r4016) | ARM OpenAPI(swagger) specs |
+| [R4017](#r4017) | [TopLevelResourcesListBySubscription](#r4017) | ARM OpenAPI(swagger) specs |


this should also be already automated.

Did you mean these rules ?:
R3027 TrackedResourceListByResourceGroup,
R3028 TrackedResourceListBySubscription
R3010 TrackedResourceListByImmediateParent

They only deal with tracked resources while the new rules will consider other resources

azure-pipelines · 2020-07-28T11:35:20Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2020-07-28T11:44:34Z

Azure Pipelines successfully started running 1 pipeline(s).

azure-pipelines · 2020-07-30T02:38:01Z

Azure Pipelines successfully started running 1 pipeline(s).

jianyexi added 2 commits July 14, 2020 12:52

add 6 lint rules feedback by ARM

1620e04

update output message

7225627

openapi-assignment-bot bot assigned josefree Jul 14, 2020

update R4017

401974b

akning-ms requested review from pilor and KrisBash July 14, 2020 06:19

improve how-to-fix of R2016

d018706

fix typos

c357122

fix typo

6088737

pilor requested review from chiragg4u, majastrz and ravbhatnagar July 14, 2020 16:58

pilor reviewed Jul 14, 2020

View reviewed changes

pilor approved these changes Jul 14, 2020

View reviewed changes

update R4019 description

d9c2b95

R4014 change to warning

13d9a64

akning-ms reviewed Jul 23, 2020

View reviewed changes

openapi-assignment-bot bot added the WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required label Jul 23, 2020

ravbhatnagar reviewed Jul 27, 2020

View reviewed changes

ravbhatnagar added ARMSignedOff <valid label in PR review process>add this label when ARM approve updates after review and removed WaitForARMFeedback <valid label in PR review process> add this label when ARM review is required labels Jul 27, 2020

rename duplicate R4000

b866bd6

update output message

42e9b5c

update

5f2ddb6

josefree approved these changes Jul 30, 2020

View reviewed changes

akning-ms merged commit 0b0c022 into master Aug 5, 2020

jianyexi deleted the update_lintdoc branch December 18, 2020 07:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add 6 lint rules feedback by ARM to the guideline #10125

Add 6 lint rules feedback by ARM to the guideline #10125

jianyexi commented Jul 14, 2020 •

edited by akning-ms

Loading

openapi-pipeline-app bot commented Jul 14, 2020 •

edited

Loading

azure-pipelines bot commented Jul 14, 2020

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

azuresdkci commented Jul 14, 2020

azure-pipelines bot commented Jul 14, 2020

azure-pipelines bot commented Jul 14, 2020

azure-pipelines bot commented Jul 14, 2020

pilor Jul 14, 2020

jianyexi Jul 16, 2020

pilor left a comment

azure-pipelines bot commented Jul 16, 2020

jianyexi commented Jul 17, 2020

jianyexi commented Jul 20, 2020

jianyexi commented Jul 20, 2020

azure-pipelines bot commented Jul 23, 2020

akning-ms Jul 23, 2020 •

edited

Loading

pilor Jul 23, 2020

akning-ms Jul 24, 2020

pilor Jul 24, 2020 •

edited

Loading

jianyexi Jul 27, 2020

ravbhatnagar Jul 27, 2020

ravbhatnagar Jul 27, 2020

jianyexi Jul 28, 2020 •

edited

Loading

azure-pipelines bot commented Jul 28, 2020

azure-pipelines bot commented Jul 28, 2020

azure-pipelines bot commented Jul 30, 2020


		Output Message : The response in the GET collection operation "{0}" is different than the response definition in the individual GET operation "{1}".

		Description : For all resources (top-level and nested), collection GETs should have a response definition with a single property "value" containing an array of the "resource" schema.The definition returned in the collection "value" array should be the same as the response body for the individual GET.


		### <a name="r4014" ></a>R4014 AllResourcesMustHaveGetOperation

		Category : ARM Warning

Add 6 lint rules feedback by ARM to the guideline #10125

Add 6 lint rules feedback by ARM to the guideline #10125

Conversation

jianyexi commented Jul 14, 2020 • edited by akning-ms Loading

Contribution checklist:

ARM API Review Checklist

Breaking Change Review Checklist

openapi-pipeline-app bot commented Jul 14, 2020 • edited Loading

[Staging] Swagger Validation Report

azure-pipelines bot commented Jul 14, 2020

openapi-sdkautomation bot commented Jul 14, 2020 • edited Loading

Azure CLI Extension Generation - Release

openapi-sdkautomation bot commented Jul 14, 2020 • edited Loading

azure-sdk-for-go - Release

openapi-sdkautomation bot commented Jul 14, 2020 • edited Loading

azure-sdk-for-java - Release

openapi-sdkautomation bot commented Jul 14, 2020 • edited Loading

azure-sdk-for-js - Release

openapi-sdkautomation bot commented Jul 14, 2020 • edited Loading

Trenton Generation - Release

openapi-sdkautomation bot commented Jul 14, 2020 • edited Loading

azure-sdk-for-net - Release

openapi-sdkautomation bot commented Jul 14, 2020 • edited Loading

azure-sdk-for-python - Release

openapi-sdkautomation bot commented Jul 14, 2020 • edited Loading

azure-sdk-for-python-track2 - Release

azuresdkci commented Jul 14, 2020

azure-pipelines bot commented Jul 14, 2020

azure-pipelines bot commented Jul 14, 2020

azure-pipelines bot commented Jul 14, 2020

pilor Jul 14, 2020

Choose a reason for hiding this comment

jianyexi Jul 16, 2020

Choose a reason for hiding this comment

pilor left a comment

Choose a reason for hiding this comment

azure-pipelines bot commented Jul 16, 2020

jianyexi commented Jul 17, 2020

jianyexi commented Jul 20, 2020

jianyexi commented Jul 20, 2020

azure-pipelines bot commented Jul 23, 2020

akning-ms Jul 23, 2020 • edited Loading

Choose a reason for hiding this comment

pilor Jul 23, 2020

Choose a reason for hiding this comment

akning-ms Jul 24, 2020

Choose a reason for hiding this comment

pilor Jul 24, 2020 • edited Loading

Choose a reason for hiding this comment

jianyexi Jul 27, 2020

Choose a reason for hiding this comment

ravbhatnagar Jul 27, 2020

Choose a reason for hiding this comment

ravbhatnagar Jul 27, 2020

Choose a reason for hiding this comment

jianyexi Jul 28, 2020 • edited Loading

Choose a reason for hiding this comment

azure-pipelines bot commented Jul 28, 2020

azure-pipelines bot commented Jul 28, 2020

azure-pipelines bot commented Jul 30, 2020

jianyexi commented Jul 14, 2020 •

edited by akning-ms

Loading

openapi-pipeline-app bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

openapi-sdkautomation bot commented Jul 14, 2020 •

edited

Loading

akning-ms Jul 23, 2020 •

edited

Loading

pilor Jul 24, 2020 •

edited

Loading

jianyexi Jul 28, 2020 •

edited

Loading