OAS 3.0: Rendering

[shockey]

This ticket tracks line items related to the rendering of OAS 3.0 specs. It does not include line items related to Try-It-Out functionality, or any UI changes to support the Editor experience.

Time estimates formatted as ##h/RiskLevel. Estimates include tests where applicable.

Work is being done in this branch.

TODO

Internal plumbing

• Add mechanism for overriding selectors based on spec content 8h/Med
  (shockey@1f314dd)
• Add mechanism for overriding components based on spec content 6h/Med (shockey@614c1ae and shockey@88848d0)

Supporting changes

• Render reorganized definitions (shockey@6093410#diff-be155ae7ebea3eda018b85efba94c8b0R41)
• Render reorganized responses 1h/Low
• Render reorganized parameters 2h/Low
• Support CommonMark in descriptions 1-2h/Low
• Render request bodies 4h/Low (Implemented, needs design work)
• Render cookie parameters 2h/Low
• Render response ranges 2h/Low
• Render callbacks 12h/Med
• Render deprecated 4h/Low
• Render links 6h/Med
• Render media types in Request Parameters, Request Body, Responses 12h/Med
• Render schema values with anyOf, oneOf, not 10h/Med
• Render nullables 1h/Low
• Render writeOnly 2h/Low

Moar changes

• Render deprecated in individual properties
• Ensure Markdown XSS protections are still present in new renderer

Even moar changes (added 6/28)

• Disable validation badge

Ignoring deprecated fields

6h/Low in aggregate

• host
• basePath
• schemes
• consumes
• produces
• definitions
• parameters
• responses

[shockey]

I moved this comment into the main ticket body.

[webron]

• Callbacks tab should not appear if there are no callbacks defined.
• Links styling needs to be fixed.
• headers no longer exist under Links (this is from RC2)
• The response content type is aligned to the left and too close to the Responses text, makes it look weird. But...
• The response content type should appear individually per response code and no longer at the top of the Responses. Each response code can have entirely different content types defined for it.
• For callbacks, disable the try it out functionality.
• Request Body:
  • Should still have a model view and example view for each content type
  • Should have the content type as a drop down, and the model/example view change based on the choice. It should not show a long list of content types as now.
  • Doesn't turn editable when try it out is enabled (no examples) - it should.

[shockey]

Status update on changes

Callbacks tab should not appear if there are no callbacks defined.

Done:

---

headers no longer exist under Links (this is from RC2)

Link headers have been annihilated.

---

The response content type is aligned to the left and too close to the Responses text, makes it look weird.

Fixed:

---

For callbacks, disable the try it out functionality.

Fixed:

Note the small lingering CSS issue inside the callback operation.

---

Request body should have the content type as a drop down, and the model/example view change based on the choice. It should not show a long list of content types as now.

Done:

---

The response content type should appear individually per response code and no longer at the top of the Responses. Each response code can have entirely different content types defined for it.

In progress - the functionality works, just need to finish guarding the code so it fails gracefully.

---

The two lingering Request Body fixes are tricky - the current implementations that provide the generated samples and editing interface are very opinionated about the incoming data (it expects Swagger 2.0 parameters) I have something in progress, but I'll have to wrap it up this weekend.

[shockey]

@webron bump - need more info on Links styling needs to be fixed