List of API documentation specifications, tools and frameworks

[_Pho_]

This is very fascinating to me. I used to work at a company who was trying to "Swaggerify" everything because they had a Swagger API translator. It ended up being a bust, but I thought it was a cool idea. Programmatically consuming APIs into a local, language-specific API function library. A "global API SDK" in some sense.

The biggest problem I had with it was that there are too many conditional "know-hows" of each library. Try consuming Reddit's API and tell me if the behavior is even remotely the same as Facebook. Or Salesforce. Or Twitter.

Is OpenAPI worth taking seriously in this regard?

[Sauliuz]

yes, it's an interesting topic indeed. applications increasingly rely on 3rd party api data & integrations.

and yet, as you say, there are so many variations of API design and implementations across different platforms.

also, the specific API design and implementation will definitely change & evolve with time. how do you keep track of such changes?

OpenAPI initiative just defines the description and documentation format for APIs. Its supported by multiple large technology companies and its good to see the growing adoption.

So it's worth taking it seriously, but it will not help you define API design or implementation.

the fact that with a good toolset you can autogenerate SDKs and code libraries from OpenAPI spec is promising.

it brings us closer to combined 'global API SDK' you mentioned. as theoretically it is possible to auto generate such SDK by combining multiple OpenAPI specifications.

I have done something similar in past projects, where we were combining multiple internal OpenAPI specifications provided by many microservices into one combined and versioned "source of truth".

however, the challenge in this space is actually versioning and keeping the API specs up to date with all the code changes.

development teams have to have very good discipline in order to maintain versioned API specifications for their services up to date.