microsoft / microsoft/api-guidelines
Documenting OData $Filter in Open API Specification
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 23.3k
- Forks
- 2.7k
- PR merge metrics
- No merged PRs in 30d
Description
For defining API specifications for our customers, there is a lot of ambiguity about which keys you can actually search by given a $filter query parameter. When using explicitly named query parameters, name, address, etc we can provide meaningful documentation on each parameter type, some examples, content type.
Are there any guidelines for documenting all the possible parameters you can have under just the one $filter query parameter in an Open API Spec?
From the specification, the best I can see that we can do is document the supported operators in the description of the query parameter:
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the OpenAPI Specification v3.1.0 fixed-fields section linked in the issue and review how a single $filter query parameter can describe its supported keys and operators. Done means the API Guidelines contain an agreed, actionable recommendation for documenting OData $filter parameters, including any examples or limitations that should be stated.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100