Specification in machine-parsable format (e.g., OpenAPI)

tumblr / docs

Tumblr's public platform documentation.

Apache License 2.0

109 stars 27 forks source link

Specification in machine-parsable format (e.g., OpenAPI) #41

Closed ThisIsMissEm closed 3 years ago

ThisIsMissEm commented 3 years ago

Currently the API is documented just through the markdown specification, which means that each client needs to be written by hand. With a specification in a format such as OpenAPI, you'd be able to automatically generate clients, rather than maintaining them by hand.

I've started some work here, but ultimately this is a side-project to a side-project: https://gist.github.com/ThisIsMissEm/682a272fe1bef10c80ae497848cca06b

cyle commented 3 years ago

Yeah, we actually have an OpenAPI implementation in the works internally, though we don't (yet) have plans to release it publicly. It would indeed make API clients easier to build.

sorin-costea commented 3 years ago

It would actually take most of the client-related work off your shoulders - when I just look at the lack of love those poor clients are getting... Java hasn't been updated in a few years already.

cyle commented 3 years ago

Closing this, but I just want to be clear that if we do end up going down this route, there'll probably be an announcement on engineering.tumblr.com and updates to these docs (obviously).