I now have wrapped a couple of API's in swagger and using swagger-ui to create beautiful interactive api docs for users.
Moving forward I'm going to wrap most of our legacy systems around a swagger spec'ed API and discontinue any alternative access to these systems as time goes by.
I'm the author, and I definitely know about Swagger/OpenAPI. By coincidence, I'm maintainer of the collection of 250+ Swagger specs for public APIs: https://github.com/APIs-guru/openapi-directory
But I have learned the hard truth over last two years: API catalogs aren't scalable solutions for API discovery. That's why I'm pushing this.
P.S. it is pretty easy to generate Schema.org type based on Swagger/OpenAPI spec.
Ah cool, thanks for the link and effort. Will have a look at it as time allow.
> It is pretty easy to generate Schema.org type based on Swagger/OpenAPI spec.
Do you have any example or gist of a snipped of code to accomplish this?
> API catalogs aren't scalable solutions for API discovery. That's why I'm pushing this.
But does the API catalog not enable auto discovery? Agreeing you maintaining a list is not scalable.
Minor critique but the word "discovery" particularly in terms of service oriented is heavily overloaded. It took me a little while to understand what the article meant by discovery and I'm still not entirely sure I do.
Do you mean this discovery: https://en.wikipedia.org/wiki/Service_discovery or do you mean a discovery more in the human sense (ie a consumer search directory listing API services)?
And here is github repo: https://github.com/APIs-guru/openapi-directory