search

OAI / learn.openapis.org

OpenAPI - Getting started, and the specification explained
https://learn.openapis.org/
Creative Commons Attribution 4.0 International
120 stars 60 forks source link

inconsistency between documentation and spec: is paths required? #25

Closed karenetheridge closed 3 years ago

karenetheridge commented 3 years ago

in https://github.com/OAI/Documentation/blob/main/specification-structure.md:

The root object in any OpenAPI document is the OpenAPI Object and only three of its fields are mandatory: openapi, info and paths.

But the schema (https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/schemas/v3.1/schema.yaml) says:

anyOf:
  - required:
    - paths
  - required:
    - components
  - required:
    - webhooks

Which one is correct?

webron commented 3 years ago

Neither of those is the specification. Not sure if the Documentation was updated to OAS 3.1 but the section you're referring to is true in OAS 3.0 but changed in OAS 3.1. The snippet from the schema is true to OAS 3.1.

karenetheridge commented 3 years ago

I also noticed that on the next page, https://oai.github.io/Documentation/specification-paths.html, says that "responses" is mandatory in the operations object, neither the spec nor the schema contain this constraint.

Have these doc pages been updated for v3.0.3->v3.1.0?

webron commented 3 years ago

Apparently, they've not been. As always, the source of truth is always the specs. For reference, https://spec.openapis.org/oas/v3.1.0.html and https://spec.openapis.org/oas/v3.0.0.html (or just https://github.com/OAI/OpenAPI-Specification/tree/main/versions).

MikeRalphson commented 3 years ago

Thanks for pointing this out @karenetheridge - do you have bandwidth to raise a PR to fix these issues? If not, I can.

karenetheridge commented 3 years ago

I can PR it this weekend.