Openapi-specification: List of existing vendor extensions.

[IvanGoncharov]

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.

[ePaul]

Such a list is a good idea, but it should not be part of the specification itself.

It could be a separate document in this repository, or in a separate repository (e.g. if different maintainers are wished).

[IvanGoncharov]

@ePaul From my first message:

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.

I still think that disclaimer is totally adequate measure.

or in a separate repository (e.g. if different maintainers are wished).

In any case, I think it's a good idea to reference such list in this repo.
In my catalog I work with hundreds of APIs and it's pretty easy for me to run grep x- on them.
I also have 6+k of unique Swagger 2.0 specs which I scraped from Github so it pretty easy for me to search for vendor extension. So I can monitor and add new extension then they appear in public specs.

I also create many vendor extension myself.
For example, right now I need to create an extension to add support for OAuth1.0: https://github.com/APIs-guru/api-models/issues/46
So I can be a maintainer if needed.

[ralfhandl]

@IvanGoncharov could you compile an initial list from your 6+k Swagger specs?

[IvanGoncharov]

@ralfhandl Currently I have some problems with my scraper, which need to be solved.
I will compile a list in the next few weeks, and post it as the separate repo.

[ralfhandl]

@IvanGoncharov Cool! I'm curious what people came up with so far. Can you include a usage count in the list?

[IvanGoncharov]

@ralfhandl I can even include lists of URLs to specs themselves.

[LarryKlugerDS]

This is a great idea! Having a catalog of extensions would enable the opportunity to re-use them by other designers. I suggest a different repo, with a pointer to it from the specification's repo. The pointer would enable people who are looking at the spec to more easily find the extensions catalog.

It is in the interest of the spec to have the extensions catalog since it will:

1. Make it even easier for people new to the spec to understand how others are using the spec
2. Show the variety of uses for the Open API spec
3. Enable great extension ideas to, over time, bubble up and to be considered for inclusion in the spec itself.

[wparad]

I suggest having this maintained by the vendor themselves (in the sort term that may mean some good Samaritan managing it until the API open steps up). Let it be community driven, by those who gain the most benefit.

I think what we really need is a recommendation on the format of these documents, and once we have that, users like @IvanGoncharov can start the vendor github pages (or wherever) to contain the appropriate documents.

[IvanGoncharov]

@wparad I think you right, it should be some simple markdown documents hosted as GitHub repo.
I created dedicated repo couple months ago: https://github.com/APIs-guru/OpenAPI-Extensions
And I think documenting extensions we use in APIs.guru is good starting point.

@ralfhandl Sorry, for the delay, I was very busy with a few other projects.
I didn't forget my promise and will try to compile the list on this week.

[ralfhandl]

@IvanGoncharov cool, waiting for your initial content as a template on how to document our extensions.

[MikeRalphson]

@ralfhandl I've taken over from @IvanGoncharov as maintainer of the APIs.guru collection and will hopefully be picking this up soon.

[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.

[MikeRalphson]

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

[JonKohler]

hey @MikeRalphson - this is great stuff. Any chance we can get an updated run of the scraper? Its very interesting to see what others are adopting

[MikeRalphson]

Hi @JonKohler it's in the pipeline yes, I just need to make sure I'm picking up the increasing number of OpenAPI 3.0.x definitions!