Documented how OpenAPI references are used #145
Conversation
|
Learn Build status updates of commit dc3380f:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| OpenAPI/OpenAPI.NET/references-openapi.md | Details |
OpenAPI/OpenAPI.NET/references-openapi.md
- Line 4, Column 9: [Warning: author-not-found - See documentation]
Invalid value for author: 'darrmi' is not a valid GitHub ID. - Line 2, Column 1: [Suggestion: ms-date-missing - See documentation]
Missing required attribute: 'ms.date'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
|
Learn Build status updates of commit f313a60:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| OpenAPI/OpenAPI.NET/references-openapi.md | Details |
OpenAPI/OpenAPI.NET/references-openapi.md
- Line 4, Column 9: [Warning: author-not-found - See documentation]
Invalid value for author: 'darrmi' is not a valid GitHub ID. - Line 2, Column 1: [Suggestion: ms-date-missing - See documentation]
Missing required attribute: 'ms.date'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
|
Learn Build status updates of commit 69f97c4:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| OpenAPI/OpenAPI.NET/references-openapi.md | Details |
OpenAPI/OpenAPI.NET/references-openapi.md
- Line 4, Column 9: [Warning: author-not-found - See documentation]
Invalid value for author: 'darrmi' is not a valid GitHub ID. - Line 2, Column 1: [Suggestion: ms-date-missing - See documentation]
Missing required attribute: 'ms.date'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
|
Learn Build status updates of commit b89b424:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| OpenAPI/OpenAPI.NET/references-openapi.md | Details |
OpenAPI/OpenAPI.NET/references-openapi.md
- Line 4, Column 9: [Warning: author-not-found - See documentation]
Invalid value for author: 'darrmi' is not a valid GitHub ID. - Line 2, Column 1: [Suggestion: ms-date-missing - See documentation]
Missing required attribute: 'ms.date'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
|
Learn Build status updates of commit c2b8bfc:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| OpenAPI/OpenAPI.NET/references-openapi.md | Details |
OpenAPI/OpenAPI.NET/references-openapi.md
- Line 4, Column 9: [Warning: author-not-found - See documentation]
Invalid value for author: 'darrmi' is not a valid GitHub ID. - Line 2, Column 1: [Suggestion: ms-date-missing - See documentation]
Missing required attribute: 'ms.date'.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
| For completeness, Reference Objects can also point to targets in a JSON/YAML document that contain properly formed OpenAPI objects, but is not a complete OpenApi document. We refer to these as OpenAPI "fragments". Currently OpenAPI.NET does not support referencing OpenAPI fragments. | ||
|
|
||
| ```yaml | ||
| openapi: 3.1.0 |
There was a problem hiding this comment.
@MaggieKimani1 I believe this one is missing from your test suite
| components: | ||
| schemas: | ||
| specialitem: # Use the item type but provide a different title for the type | ||
| title: Special Item |
There was a problem hiding this comment.
sanity check here, should this demonstrate the summary or description property instead? I was under the impression those were the only two overridable properties through ref. But it might be true for anything BUT JSON schema references.
If JSON schema references allow more properties to be overridden, we do have to implement a bunch of changes in the models.
| - 'null' | ||
| properties: | ||
| b: | ||
| $ref: '#/properties/b' |
There was a problem hiding this comment.
this one looks odd to me, if I go "up one schema" I end up in the schema definition of b, which does not contain any b property. Maybe I'm using the wrong "resolving routine", in which case I believe we should document the routine one should apply here.
| additionalProperties: false | ||
| properties: | ||
| b: | ||
| $ref: '#/properties/d' |
There was a problem hiding this comment.
assuming the routine to apply here is "go find the closed defined id in the parents, and start resolving from there"? we should detail that information.
| additionalProperties: false | ||
| properties: | ||
| c: | ||
| $id: 'http://example.org/c' |
There was a problem hiding this comment.
@MaggieKimani1 I believe we're missing this one in the test cases
| ### What can a JSON Schema locator reference target | ||
|
|
||
| - An internal component | ||
| - An interal component subschema |
There was a problem hiding this comment.
| - An interal component subschema | |
| - An internal component subschema |
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: 'OAS-schemas.yaml#/components/schemas/person' |
There was a problem hiding this comment.
in terms of URI here, what conventions can be applied?
is this equivalent to having ./ in front? What about / in front? Do we have an RFC we can leverage here?
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: 'https://schemas.acme.org/address' |
There was a problem hiding this comment.
I'm assuming this is based on URI conventions. If the id was /address, it'd have been equivalent. But if it were ./address the ref should have been https://schema.acme.org/person/address ?
Maybe worth calling out even if we don't implement it/fully spec it yet.
| paths: | ||
| /jobs/{id}: | ||
| get: | ||
| $ref: '#/components/pathItems/job' |
There was a problem hiding this comment.
is this indented properly? shouldn't it be that?
| $ref: '#/components/pathItems/job' | |
| $ref: '#/components/pathItems/job' |
No description provided.