search

Azure / azure-openapi-validator

Azure Open API Validator
MIT License
47 stars 46 forks source link

[new rule]: Validate the url in swagger #368

Open pshao25 opened 2 years ago

pshao25 commented 2 years ago

Lint rule description

We downstream autorest.csharp will consume the url in externalDocs to generate method comments, e.g., https://github.com/Azure/azure-sdk-for-net/blob/cf65e6c89774de4dce4fe7b7e65f83b303464278/sdk/cognitivelanguage/Azure.AI.Language.Conversations/src/Generated/ConversationAnalysisClient.cs#L395-L396. The value in the externalDocs.url will be put into the above comments.

But this link might be invalid. We need a way to validate this.

Related swagger example

https://github.com/Azure/azure-rest-api-specs/blob/88e7838a09868a51de3894114355c75929847a46/specification/search/data-plane/Microsoft.Azure.Search.Service/preview/2017-11-11-preview/searchservice.json#L105-L107

Category

Documentation

Severity level

Error

Applies to

Management plane API spec, Data plane API spec, RPaaS API spec

How to fix the violation

Fail the validation.

What't the impact if breaking the rule

User will click a corrupted link.

jianyexi commented 2 years ago

@ArthurMa1978 we've discussed it, still have below concerns:

  1. might cause security issue when open an unknown url
  2. just checking the url is valid is not enough to ensure the url is correct url for the operation, we need to analyze more real-world cases to come up with an ideal solution