search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.91k stars 9.07k forks source link

Structural improvements: move root externalDocs to info #685

Closed arno-di-loreto closed 4 months ago

arno-di-loreto commented 8 years ago

This issue is quite simple it's only about moving the root externalDocs into the info object to simplify root.

before:

info:
  # (existing) info object
externalDocs:
  # link to some external documentation about the API

after:

info:
  # (existing) info object + externalDocs
  (... same properties as existing info object)
  externalDocs:
    # (existing) Moving externalDocs from root to info
darrelmiller commented 8 years ago

I'm not sure I see the benefits. Yes the root has one less property, but now the info object has one more. What is the benefit of having less properties in the root?

I don't feel strongly one way or the other, but if we are going to make a breaking change then I think we should have a fairly good justification.

darrelmiller commented 8 years ago

Having now read OAI/sig-moonwalk#115 I see the reason for your proposal.

arno-di-loreto commented 8 years ago

parent OAI/OpenAPI-Specification#560

handrews commented 4 months ago

Closing this as included in

as it would be part of a major version change to remove/move a top-level field.