Feat/41/overlay curriculum#42
Conversation
lornajane
left a comment
lornajane
left a comment
There was a problem hiding this comment.
Epically slow response, sorry. Added some first-pass comments.
|
|
||
| ## Course Audience | ||
|
|
||
| Overlay Fundamentals is expected to be a available to a wide range of |
There was a problem hiding this comment.
| Overlay Fundamentals is expected to be a available to a wide range of | |
| Overlay Fundamentals is expected to be available to a wide range of |
|
|
||
| - Explain how API economy has been shaped by use of API description languages. | ||
|
|
||
| - Describe the relationship between the Overlay Specification and Overlay |
There was a problem hiding this comment.
| - Describe the relationship between the Overlay Specification and Overlay | |
| - Describe the relationship between the Overlay Specification and OpenAPI |
| - Describe the relationship between the Overlay Specification and Overlay | ||
| Specification. | ||
|
|
||
| - Describe how Overlay supports creation of OpenAPI descriptions. |
There was a problem hiding this comment.
Might be more accurate to say it supports transformation rather than creation. This isn't an authoring tool.
| - Demonstrate how Overlay can be executed after the creation of an OpenAPI | ||
| description. | ||
|
|
||
| - Provide a pipeline-based view of this activity executed alongside other |
There was a problem hiding this comment.
One thing that I think is really key with the pipeline content is to convey that we don't have one OpenAPI, but rather with Overlays we us a single source of truth to prepare output for multiple destinations. It's about dropping endpoints that are not for a particular audience. Or adding metadata hints to get better outputs from the code generators without making that extra content go into every output tool.
|
|
||
| - Legal disclaimer. | ||
|
|
||
| - Added API security features, for example: |
There was a problem hiding this comment.
Major use case: API shaping. Remove the deprecated/experimental/internal endpoints that don't want to be in docs.
|
|
||
| - Show examples in context of an OpenAPI description document. | ||
|
|
||
| - Behavior of an `update` Action: |
There was a problem hiding this comment.
If you want to bump to Overlay 1.1, that also has "copy" and there are docs on the learn site as well as the spec.
| OpenAPI description document, with features that clearly indicate the role | ||
| Overlay is playing in updating the document. | ||
|
|
||
| - Describe practices for storing Overlay document: |
|
|
||
| - Governed alongside OpenAPI documents. | ||
|
|
||
| ## Chapter 5: Extending Overlay |
There was a problem hiding this comment.
I haven't seen a lot of this in the wild yet, which isn't to say we shouldn't include it.
|
|
||
| - Behavior of an `update` Action: | ||
|
|
||
| - Target object must be exist. |
There was a problem hiding this comment.
| - Target object must be exist. | |
| - Target object must exist. |
|
|
||
| - Behavior of `remove` Action. | ||
|
|
||
| - Target object must be exist. |
There was a problem hiding this comment.
| - Target object must be exist. | |
| - Target object must exist. |
There was a problem hiding this comment.
Must it? If the overlay doesn't match anything, I think that's fine. Like if you add a specific tag to DELETE events, but then apply that overlay to an OpenAPI description that does not have any of those, no problem.
2 participants
Summary of changes:
If you are reviewing, please see curriculum document for all details of what is included in the PR 👍 .