Refined guidelines for external file reuse #535
Conversation
|
|
||
| Reuse schema definitions by creating a repository of definitions. This is done by simply hosting a file or set of files for commonly used definitions across a company or organization. | ||
|
|
||
| Refer to [External references](#external-references) for referencing strategies. |
There was a problem hiding this comment.
Intentionally left this section pretty empty, as #external-references has so many definition/schema examples.
There was a problem hiding this comment.
JSON References can reference within the same document so I think the "creating a repository of definitions" is misleading. In fact, Swagger already uses this for parameters, responses, definitions, ...
I think the point of reuse is to suggest that reuse is enable through the use of JSON References. If we need to explain more about JSON References, do it of course.
There was a problem hiding this comment.
<again, existing wording I tried to preserve>
You could say that parameters, responses, definitions are "repositories of definitions", which happen to reside in the same document (vs external files).
|
@jasonh-n-austin - let me know when the PR is ready to be merged. |
|
@webron @whitlockjc @BigstickCarpet refactored based on PR/issue discussion.
|
| * Parameters | ||
| * Responses | ||
| * Models (or Schema Objects in general) |
There was a problem hiding this comment.
Minor nit but for consistency, either italicize this or remove the italicization from the line below.
|
Please don't hate me. :) The biggest issue I had wasn't your fault and could likely be ignored for now and addressed later. The other pieces of feedback are all small. |
|
@whitlockjc love it...keep it coming. Doc updates with no feedback are meaningless; updates with lots of feedback are always higher quality. |
|
@whitlockjc commit'd fixes, with some rewording for brevity and consistency. Gimmee some |
! 😺
| The reuse technique is transparent between JSON or YAML and is lossless when converting between the two. | ||
| When authoring API design documents, common object definitions can be utilized to avoid duplication. For example, imagine multiple path definitions that each share a common path parameter, or a common response structure. The OpenAPI specification allows reuse of common object definitions through the use of "references". | ||
|
|
||
| A reference a construct in your API design document that indicates "the content for this portion of the document is defined elsewhere". To create a reference, at the location in your document where you want to reuse some other definition, create an object that has a `$ref` property whose value is a URI pointing to where the definition is (more on this in later sections). |
There was a problem hiding this comment.
"A reference a" should be "A reference is a".
|
Two minor nits, one of which is a formatting issue. After that, I don't see why this can't be merged. Good job. |
|
OK fixed up content tweaks. @webron should be good for merge. Squirrel me! |
| @@ -92,14 +147,14 @@ _Assuming file https://my.company.com/definitions/Model.json_ | |||
| "format": "int64" | |||
| }, | |||
| "tag": { | |||
| "description": "a complex, shared property. Note the absolute reference", | |||
| "description": "A complex, shared property. Note the absolute reference", | |||
There was a problem hiding this comment.
I know this was in the original example as well, but the description is obviously ignored and does not override the value inside the reference (as previously mentioned in the doc). I get this is used here for documentation to the readers, but it may also send the wrong message. I'll merge as-is, but we may consider removing it after all.
|
Thanks all for the great work on this, and apologies for the delay in merging. I think we're good to go. |
Refined guidelines for external file reuse
Fairly big refactor of this section, to address #388
SwaggertoOpenAPI Specification(I presumed we're doing this on any updates to docs now)