What do you use for defining & documenting your APIs?

I ask because this is something the UK Government is looking at - https://github.com/alphagov/tech-and-data-standards/issues/3...

The best part about Swagger is there's a lot of good open-source tooling for it (though this depends on the language).

One alternative I find super interesting lately is defining APIs with grpc and then exposing them with the gateway proxy: https://github.com/grpc-ecosystem/grpc-gateway

In this way, you get strongly-typed interfaces and Swagger is autogenned for you.

I think most are crafted by hand. Maybe the problem is similar to language, compiler and interpreter design. There exists specific software that tries to help you with providing solutions for sub-problems (lexers and parser-generators), but they are hardly used, as they are hard to customize (see a recent discussion about writing a recursive descent parser), so people hand-craft them.

When designing an API the hard part is getting it right(tm) and hopefully guarantee some kind of backwards compatibility and providing a clear path for its consumers, in particular documentation. It is possible to auto-generate some parts of the documentation, but such documentation is probably as helpful as auto-generated javadoc without notes provided by humans.

RAML https://www.google.co.nz/url?sa=t&rct=j&q=&esrc=s&source=web..., with json schema http://json-schema.org/

And it is. If you perform some API Governance in your company, odds are that they are performed with Swagger. RAML and Blueprint are losing adoption.

Unfortunately you're mistaken. Most companies just don't care and document their APIs by hand on internal wiki. If they document at all.

From my experience it doesn't define it. However its becoming the standard for documenting your REST based HTTP API's and it's a focal point of the API itself to developers/stakeholders.