Am I the only one that's dissatisfied with the state of API design specs? API Blueprint feels dead in the water, RAML and Swagger feel too verbose (not the biggest fan of YAML in this specific usecase) or would rely too heavily on codegen.

I feel like API Blueprint was the closest to what I actually wanted. Inheritance / types felt natural and specifying a JSON schema separate from an example made more sense to me. Plus it was just straight up Markdown + their MSON format, rather than trying to shoehorn in YAML.

The simplicity of it being Markdown + MSON meant you could open it up in any old editor, not need something like API Workbench in Atom to create the most optimal design experience.

I've just at this point resigned to two options:

1. Write things in Markdown with no additional structure. Not especially viable for long term API design and iteration, hard to develop tooling around.
2. Write my own spec. Yay yet another "standard" /s



Have you looked at some of the language-specific documentation tools for inspiration? I've heard good things about the documentation tooling in and , for example. (I know that supports and inline testing of code within docs, which seems like it'd be very helpful for API documentation.)

@codesections Yea I use Go documentation + godoc, however lang-specific docs are designed to be used in conjunction with its respective language (obviously) as opposed to being more agnostic like a RESTful API design that could be implemented with one or more languages. Lang-specific docs make the most sense for when you're integrating it directly (package importing, as an example) or for bindings IMO.


That makes sense. I was more thinking in terms of if you do write your own spec—if you wrote something that was basically "godoc for API documentation", then it would *technically* contribute to the yet-another-standard problem, but it might not feel like it was adding something "new" in the same way that a wholly new standard might.

But the use cases might be different enough that that doesn't really work… hmm, not sure.

@codesections Yea if I am going to write some new API design specification, it'll be specifically for RESTful APIs and stray away from being tied to a specific codebase. I think inlining a spec with complex data like JSON schemas, HTTP method specific params, etc. would be a disaster, in addition to likely being harder to parse (needing lang-specific parsers, for example) or to getting multiple parties involved in the design process (handy for contracted design work).

Sign in to participate in the conversation

Fosstodon is a Mastodon instance that is open to anyone who is interested in technology; particularly free & open source software.