List of existing vendor extensions.

Right now many project/companies start to use OpenAPI specification and in a lot of the cases they create vendor extension. It could be something simple as add logo URL(cases for my catalog) or more advanced things like rate limiting. I don’t think they should be in core spec but at the same time inventing your own extension is tricky business.

I think a good middle ground is to create the list of existing vendor extension along with the tools supporting them. To prevent possible confusion disclaimer could be added stating that the following extension doesn’t have anything to do with OpenAPI and provided here just for reference purposes.

Few examples of existing extensions, living in vendor specific namespaces: https://github.com/apigee-127/a127-documentation/wiki/Swagger-specification-file#user-content-apigee-127-swagger-specification-reference https://support.3scale.net/howtos/api-configuration#gist27263507 https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/creating-swagger.md#Enum-x-ms-enum

On the other hand, there are a few generic vendor-neutral extensions: https://help.apiary.io/api_101/swagger-extensions/ https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md

IMHO, I think vendor extensions are a necessary evil since core spec can’t accommodate all possible scenarios. But currently, vendors creating whole domains of vendor extensions(like x-sas-*, x-ms-*, etc.) which is very similar to what happened with CORBA, WSDL, etc.

I think such list will stimulate people to reuse existing integration instead of inventing a new one. And a smaller set of more generic extension is definitely better than each company creating its own OpenAPI dialect. Moreover, if some extension gains a lot of support in lib/tool it will make a good candidate to add in future versions of OpenAPI itself.

[MikeRalphson]

Analysis now performed over 49,336 API definitions from GitHub, SwaggerHub, APIs.guru, SOM-Research and Mermade collections.

[MikeRalphson]

I’ve analysed about 1500 definitions from GitHub (I omitted all repositories which were forks, and only looked for files named swagger.json or swagger.yaml, hence less than @IvanGoncharov’s 6000).

The raw list is here.

APIs.guru’s specification extensions are documented here. This also includes a list of pointers to other vendor documentation.