Forum Discussion

christw's avatar
christw
New Member
6 years ago

OpenAPI 2.0 vs 3.0 - Which one to choose

When creating a new api documentation in swaggerhub I can choose between version 2.0 and 3.0.

2.0 ist the default option. I was wondering if there is any reason for this. Any downside when using the newer 3.0 version (with swaggerhub)?

1 Reply

Sort By
  • RonRatovsky's avatar
    RonRatovsky
    Moderator
    6 years ago

    Hello!

     

    That's a great question! We can't make the decision for you, but maybe with some additional information it would help you make the decision on your own.

     

    The help section contains some information about using OAS 3 in SwaggerHub, with details about what's not supported. The existing limtations regularly change and more support is added regularly.

     

    Here are some questions you want to ask yourself before making a decision:

    • What parts of the API Lifecycle am I looking to invest into and control? For example, if it's documentation only, OAS3 is a better option. If it's integrating with APIM systems, then OAS2 would be wiser (most APIM system do not support OAS3 yet).
    • Are there any features in OAS3 that are cruicial to my API design? Among other things, OAS3 supports better example documentation, security definitions, reusability and callbacks.
    • Do I need to create a common library of definitions and reuse it among multiple APIs? Domain support for OAS3 is not yet available, though it is in the works. Update: OAS3 Domains are now supported.

    Keep in mind that through SwaggerHub, you can convert OAS2 definitions to OAS3 at any time, but not the other way around.