microsoft / microsoft/api-guidelines
Capture rules relative to required fields and how they should be modeled in OpenAPI
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
The following rules need to be captured, either in a section on JSON models OR in a complementary document on OpenAPI.
If you also support PUT then, then model depends on whether you have a required fields or not.
If you have no required fields, then again, you can use 1 model for everything.
If you have some required fields, then create a model with the required fields for PUT request/response, GET response, and PATCH response. Use a separate model where NO fields are required for PATCH request.
Also, note that you can never add new required fields to a model as this is a breaking change.
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 by locating the section on JSON models or the complementary OpenAPI document mentioned in the issue. Capture the PUT, GET, and PATCH model rules for APIs with and without required fields, and document that adding new required fields is a breaking change. Done means the rules are clearly included in the relevant guidelines.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100