Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Defender (RiskIQ) - EASM] Api version 2024-03-01-preview #28322

Open
wants to merge 44 commits into
base: main
Choose a base branch
from

Conversation

juyoung98
Copy link
Member

@juyoung98 juyoung98 commented Mar 19, 2024

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 API Spec engagement record.

  • Link to API Spec 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 API Spec document (if applicable), and the root paths that have been updated.

Viewing API changes

For convenient view of the API changes made by this PR, refer to the URLs provided in the table
in the Generated ApiView comment added to this PR. You can use ApiView to show API versions diff.

Suppressing failures

If one or multiple validation error/warning suppression(s) is detected in your PR, please follow the
Swagger-Suppression-Process
to get approval.

❔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.

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

Tooling

Guidelines & Specifications

Helpful Links

Checks stuck in `queued` state? If the PR CI checks appear to be stuck in `queued` state, please add a comment with contents `/azp run`. This should result in a new comment denoting a `PR validation pipeline` has started and the checks should be updated after few minutes.

fix #28855
fix #28855

@juyoung98 juyoung98 requested a review from a team as a code owner March 19, 2024 17:29
@juyoung98 juyoung98 requested review from weidongxu-microsoft and mikekistler and removed request for a team March 19, 2024 17:29
Copy link

openapi-pipeline-app bot commented Mar 19, 2024

Next Steps to Merge

Next steps that must be taken to merge this PR:
  • ❌ Your PR requires an API stewardship board review as it introduces a new API version (label: new-api-version). Schedule the review by following aka.ms/azsdk/onboarding/restapischedule.
  • ❌ The required check named Automated merging requirements met has failed. This is the final check that must pass. Refer to the check in the PR's 'Checks' tab for details on how to fix it. In addition, refer to step 4 in the PR workflow diagram

Copy link

openapi-pipeline-app bot commented Mar 19, 2024

Swagger Validation Report

️️✔️BreakingChange succeeded [Detail] [Expand]
There are no breaking changes.
️️✔️Breaking Change(Cross-Version) succeeded [Detail] [Expand]
There are no breaking changes.
Compared specs (v0.10.8) new version base version
easm.json 2024-03-01-preview(eec2d5b) 2023-03-01-preview(main)
️️✔️CredScan succeeded [Detail] [Expand]
There is no credential detected.
️⚠️LintDiff: 13 Warnings warning [Detail]
Compared specs (v2.2.2) new version base version
2024-03-01-preview 2024-03-01-preview(eec2d5b) default(main)

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

Rule Message Related RPC [For API reviewers]
⚠️ PaginationResponse Operation might be pageable. Consider adding the x-ms-pageable extension.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L240
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L250
⚠️ ListInOperationName Since operation response has model definition in array type, it should be of the form '_list'.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L351
⚠️ PaginationResponse value property in pageable response should be required
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L379
⚠️ PaginationResponse Operation might be pageable. Consider adding the x-ms-pageable extension.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L407
⚠️ ListInOperationName Since operation response has model definition in array type, it should be of the form '_list'.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L454
⚠️ OperationId OperationId for get method on a collection should contain 'List'
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L455
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L506
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L933
⚠️ PaginationResponse Operation might be pageable. Consider adding the x-ms-pageable extension.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1110
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1827
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1873
⚠️ EnumInsteadOfBoolean Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L7105


The following errors/warnings exist before current PR submission:

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

Rule Message
⚠️ SecurityDefinitionDescription Security definition should have a description.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L43
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L204
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L600
⚠️ PutRequestResponseScheme A PUT operation request body schema should be the same as its 200 response schema, to allow reusing the same entity between GET and PUT. If the schema of the PUT request body is a superset of the GET response body, make sure you have a PATCH operation to make the resource updatable. Operation: 'DataConnections_CreateOrReplaceDataConnection' Request Model: 'parameters[2].schema' Response Model: 'responses[200].schema'
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L634
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L644
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L696
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L837
⚠️ PutRequestResponseScheme A PUT operation request body schema should be the same as its 200 response schema, to allow reusing the same entity between GET and PUT. If the schema of the PUT request body is a superset of the GET response body, make sure you have a PATCH operation to make the resource updatable. Operation: 'DiscoveryGroups_CreateOrReplaceDiscoGroup' Request Model: 'parameters[2].schema' Response Model: 'responses[200].schema'
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L871
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L881
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L976
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1028
⚠️ PaginationResponse value property in pageable response should be required
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1035
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1265
⚠️ PaginationResponse Operation might be pageable. Consider adding the x-ms-pageable extension.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1301
⚠️ PaginationResponse Operation might be pageable. Consider adding the x-ms-pageable extension.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1434
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1542
⚠️ PutRequestResponseScheme A PUT operation request body schema should be the same as its 200 response schema, to allow reusing the same entity between GET and PUT. If the schema of the PUT request body is a superset of the GET response body, make sure you have a PATCH operation to make the resource updatable. Operation: 'SavedFilters_CreateOrReplaceSavedFilter' Request Model: 'parameters[2].schema' Response Model: 'responses[200].schema'
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1576
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1586
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1638
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1735
⚠️ PathParameterSchema Path parameter should specify a maximum length (maxLength) and characters allowed (pattern).
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1781
⚠️ EnumInsteadOfBoolean Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L1932
⚠️ EnumInsteadOfBoolean Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L2315
⚠️ EnumInsteadOfBoolean Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L2382
⚠️ EnumInsteadOfBoolean Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L2400
⚠️ EnumInsteadOfBoolean Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L2496
⚠️ EnumInsteadOfBoolean Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L2589
⚠️ EnumInsteadOfBoolean Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L2807
⚠️ EnumInsteadOfBoolean Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L2975
⚠️ EnumInsteadOfBoolean Booleans properties are not descriptive in all cases and can make them to use, evaluate whether is makes sense to keep the property as boolean or turn it into an enum.
Location: Microsoft.Easm/preview/2024-03-01-preview/easm.json#L3131
️️✔️Avocado succeeded [Detail] [Expand]
Validation passes for Avocado.
️️✔️SwaggerAPIView succeeded [Detail] [Expand]
️️✔️TypeSpecAPIView 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.
️️✔️SpellCheck succeeded [Detail] [Expand]
Validation passes for SpellCheck.
️️✔️Lint(RPaaS) succeeded [Detail] [Expand]
Validation passes for Lint(RPaaS).
️️✔️PR Summary succeeded [Detail] [Expand]
Validation passes for Summary.
️️✔️Automated merging requirements met succeeded [Detail] [Expand]
Posted by Swagger Pipeline | How to fix these errors?

Copy link

openapi-pipeline-app bot commented Mar 19, 2024

Swagger Generation Artifacts

️️✔️ApiDocPreview succeeded [Detail] [Expand]
 Please click here to preview with your @microsoft account. 
️❌ azure-sdk-for-net-track2 failed [Detail]
  • Failed in generating from d4c4688. 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/riskiq/data-plane/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
    cmderr	[Invoke-GenerateAndBuildV2.ps1] GeneratePackage: /mnt/vss/_work/1/s/azure-sdk-for-net/eng/scripts/Invoke-GenerateAndBuildV2.ps1:131
    cmderr	[Invoke-GenerateAndBuildV2.ps1] Line |
    cmderr	[Invoke-GenerateAndBuildV2.ps1]  131 |                GeneratePackage `
    cmderr	[Invoke-GenerateAndBuildV2.ps1]      |                ~~~~~~~~~~~~~~~~~
    cmderr	[Invoke-GenerateAndBuildV2.ps1]      | Failed to build sdk. exit code: False
    cmderr	[Invoke-GenerateAndBuildV2.ps1] GeneratePackage: /mnt/vss/_work/1/s/azure-sdk-for-net/eng/scripts/Invoke-GenerateAndBuildV2.ps1:131
    cmderr	[Invoke-GenerateAndBuildV2.ps1] Line |
    cmderr	[Invoke-GenerateAndBuildV2.ps1]  131 |                GeneratePackage `
    cmderr	[Invoke-GenerateAndBuildV2.ps1]      |                ~~~~~~~~~~~~~~~~~
    cmderr	[Invoke-GenerateAndBuildV2.ps1]      | Failed to packe sdk. exit code: False
    cmderr	[Invoke-GenerateAndBuildV2.ps1] Get-ChildItem: /mnt/vss/_work/1/s/azure-sdk-for-net/eng/scripts/automation/GenerateAndBuildLib.ps1:807
    cmderr	[Invoke-GenerateAndBuildV2.ps1] Line |
    cmderr	[Invoke-GenerateAndBuildV2.ps1]  807 |  … rtifacts += Get-ChildItem $artifactsPath -Filter *.nupkg -exclude *.s …
    cmderr	[Invoke-GenerateAndBuildV2.ps1]      |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    cmderr	[Invoke-GenerateAndBuildV2.ps1]      | Cannot find path
    cmderr	[Invoke-GenerateAndBuildV2.ps1]      | '/mnt/vss/_work/1/s/azure-sdk-for-net/artifacts/packages/Debug/' because
    cmderr	[Invoke-GenerateAndBuildV2.ps1]      | it does not exist.
    cmderr	[Invoke-GenerateAndBuildV2.ps1] GeneratePackage: /mnt/vss/_work/1/s/azure-sdk-for-net/eng/scripts/Invoke-GenerateAndBuildV2.ps1:131
    cmderr	[Invoke-GenerateAndBuildV2.ps1] Line |
    cmderr	[Invoke-GenerateAndBuildV2.ps1]  131 |                GeneratePackage `
    cmderr	[Invoke-GenerateAndBuildV2.ps1]      |                ~~~~~~~~~~~~~~~~~
    cmderr	[Invoke-GenerateAndBuildV2.ps1]      | Failed to generate sdk artifact
  • Azure.Analytics.Defender.Easm [Preview SDK Changes]
    info	[Changelog]
️️✔️ azure-sdk-for-js succeeded [Detail] [Expand]
  • ️✔️Succeeded in generating from d4c4688. SDK Automation 14.0.0
    command	sh .scripts/automation_init.sh ../azure-sdk-for-js_tmp/initInput.json ../azure-sdk-for-js_tmp/initOutput.json
    warn	File azure-sdk-for-js_tmp/initOutput.json not found to read
    warn		specification/riskiq/data-plane/readme.md skipped due to azure-sdk-for-js not found in swagger-to-sdk
    command	sh .scripts/automation_generate.sh ../azure-sdk-for-js_tmp/generateInput.json ../azure-sdk-for-js_tmp/generateOutput.json
  • ️✔️@azure-rest/defender-easm-rest [Preview SDK Changes]
    • azure-rest-defender-easm-rest-1.0.0-beta.1.tgz
    info	[Changelog]
    error	breakingChangeTracking is enabled, but version or changelogItem is not found in output.
️❌ azure-sdk-for-java failed [Detail]
  • Failed in generating from d4c4688. SDK Automation 14.0.0
    command	./eng/mgmt/automation/init.sh ../azure-sdk-for-java_tmp/initInput.json ../azure-sdk-for-java_tmp/initOutput.json
    warn		specification/riskiq/data-plane/readme.md skipped due to azure-sdk-for-java not found in swagger-to-sdk
    command	./eng/mgmt/automation/generate.py ../azure-sdk-for-java_tmp/generateInput.json ../azure-sdk-for-java_tmp/generateOutput.json
    cmderr	[generate.py] [COMPILE] Maven build fail.
    cmderr	[generate.py] One reason of the compilation failure is that the existing code customization in SDK repository being incompatible with the class generated from updated TypeSpec source. In such case, you can ignore the failure, and fix the customization in SDK repository.
    cmderr	[generate.py] You can inquire in "Language - Java" Teams channel. Please include the link of this Pull Request in the query.
  • azure-analytics-defender-easm [Preview SDK Changes]
    • pom.xml
Posted by Swagger Pipeline | How to fix these errors?

Copy link

PR validation pipeline can not start as the pull request is not merged or mergeable - most likely it has merge conflicts.

Copy link
Member

@weidongxu-microsoft weidongxu-microsoft left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There seems to be major changes to the new api-version.

Make sure you had scheduled an API review meeting.

@doc("Version 2023-03-01-preview")
#suppress "@azure-tools/typespec-azure-core/documentation-required" "Documentation will be added next preview version"

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see the reason why you replace a doc with a suppress?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this was a mistake. We will add it back. Thanks

@doc("A request body used to export an asset.")
@Versioning.added(Versions.v2024_03_01_preview)
model AssetsExportRequestBody {
#suppress "@azure-tools/typespec-azure-core/documentation-required" "Documentation will be added next preview version"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this "Documentation will be added next preview version" is a valid approach.

Please add them in THIS version. <-- you can wait after API review, but definitely before merge

@juyoung98
Copy link
Member Author

There seems to be major changes to the new api-version.

Make sure you had scheduled an API review meeting.

There are no breaking changes so this PR wasn't labeled that we need a review. We are only adding new endpoints, not making breaking changes. Do we still need a review? If so, why?

@weidongxu-microsoft
Copy link
Member

There seems to be major changes to the new api-version.
Make sure you had scheduled an API review meeting.

There are no breaking changes so this PR wasn't labeled that we need a review. We are only adding new endpoints, not making breaking changes. Do we still need a review? If so, why?

https://eng.ms/docs/products/azure-developer-experience/design/api-review

This was referenced Apr 26, 2024

@doc("A request body used to retrieve a delta summary.")
@Versioning.added(Versions.v2024_03_01_preview)
model DeltaSummaryRequestBody {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove the "body" suffix. Is either value required? What happens if you provide neither?

Copy link

PR validation pipeline can not start as the pull request is not merged or mergeable - most likely it has merge conflicts.

Copy link

PR validation pipeline can not start as the pull request is not merged or mergeable - most likely it has merge conflicts.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[RiskIQ - EASM - Defender EASM] API Review
7 participants