[Meta Issue] Specification documentation structure and supporting docs

[webron]

This does not cover what the spec actually support, but rather how the specification documentation itself is provided. This issue will also cover suggestions for supporting docs.

Please don't add comments directly to this issue.

[fehguy]

@OAI/tdc please send some feedback for documentation structure

[RobDolinMS]

I'll look to @webron for some advice / mentoring on this.

[RobDolinMS]

Will look at adding an index / table of contents (ToC): #673

[fehguy]

@OAI/tdc here's an inventory of the documentation items for review / examples:

Metadata

• OpenAPI Object @fehguy
• Info Object @fehguy
• Version clarification @fehguy (added version clarification #901)
• Host Servers Object @fehguy
• Contact Object @fehguy
• License Object @fehguy
• Tag Object @fehguy

Paths + operations + body parameters

• Paths Object @fehguy
• Path Item Object @fehguy
• Operation Object @fehguy
• External Documentation Object @fehguy
• Parameter Object @fehguy
• Request Body Object @fehguy
• Items Object @whitlockjc + @webron (Updated Header Object, removed Items Object #897)
• Path Templating @darrelmiller

Responses + payloads

• Responses Object @fehguy (minor doc updates for #589 #887)
• Response Object @fehguy (minor doc updates for #589 #887)
• Example Object @fehguy (Examples documentation #893)
• Examples Object @fehguy (Examples documentation #893)
• Links Object @darrelmiller
• Callbacks @darrelmiller
• Response Payload Values
• Headers Object @webron
• Header Object @webron
• JSON Reference Object @webron
• Schema Object @webron
• XML Object @webron

Reuse

• Components Object @darrelmiller
• Definitions Object @darrelmiller
• Parameters Definitions Object @darrelmiller
• Responses Definitions Object @darrelmiller

Security

• Security Definitions Object @darrelmiller
• Security Scheme Object @darrelmiller
• Scopes Object @darrelmiller
• Security Requirement Object @darrelmiller

[handrews]

This meta-issue has served its purpose, and any remaining items are being tracked under new labeling now.