Confused by multiple documentations for OpenAPI
Hi,
I found the following page while trying to understand how inheritance is handled in openAPI:
This page: Inheritance and Polymorphism (swagger.io) has the label/warning that says: This guide is for OpenAPI 3.0.
There is also another page that is also the specification: https://swagger.io/specification but the overall style and flow of these two pages are significantly different. For example, the first one contains a section titled "What is OpenAPI". The second one reads more like a reference.
Why are there two urls for the specification? Is the second one supposed to replace the first? Do they overlap? Some guidance from the community would help me navigate content more efficiently 🙂
Hi serefarikan !
The first is a guide to the OpenAPI specification and the second is the OpenAPI specification itself.
The guide is designed to help get folks familiar with the specification as it walks the reader through the different parts.
Guide to the specification: https://swagger.io/docs/specification/about/
To make it easier to navigate the official specification, there also exists a website that should be one-to-one with the official specification -- and a littler easier to navigate.
Official OpenAPI specification for 3.0.3: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md
Mirrored version of specification: https://swagger.io/specification/
These two links should contain the same information.
If in doubt the official OpenAPI specification is hosted at: https://github.com/OAI/OpenAPI-Specification where the OpenAPI community update a single markdown document per version of the specification, eg: 2.0, 3.1.0.
Hope that helps!
