4 ms·

"Over the past few years, Swagger 2 has become the de facto standard for defining your API." - LOL. I stopped reading here.

edent 10y ago
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/31 https://github.com/alphagov/tech-and-data-standards/issues/3...
- zeptomu 10y ago
  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.
- bpicolo 10y ago
  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 https://github.com/grpc-ecosystem/grpc-gateway In this way, you get strongly-typed interfaces and Swagger is autogenned for you.
- pbreit 10y ago
  http://readme.io http://readme.io
- abraae 10y ago
  RAML https://www.google.co.nz/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=0ahUKEwjki62Kw-nSAhVY4mMKHTZuDUcQFggYMAA&url=http%3A%2F%2Framl.org%2F&usg=AFQjCNHgdH2y7WIeufmJZnvELzPW4zh0SA&sig2=aEMZhHtISM-VLiK2QfFIag&bvm=bv.150120842,d.dGc https://www.google.co.nz/url?sa=t&rct=j&q=&esrc=s&source=web..., with json schema http://json-schema.org/ http://json-schema.org/
joshuaduffy 10y ago
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.
fcanela 10y ago
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.
- wst_ 10y ago
  Unfortunately you're mistaken. Most companies just don't care and document their APIs by hand on internal wiki. If they document at all.

edent 10y ago

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/31 https://github.com/alphagov/tech-and-data-standards/issues/3...

zeptomu 10y ago
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.
bpicolo 10y ago
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 https://github.com/grpc-ecosystem/grpc-gateway In this way, you get strongly-typed interfaces and Swagger is autogenned for you.
pbreit 10y ago
http://readme.io http://readme.io
abraae 10y ago
RAML https://www.google.co.nz/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=0ahUKEwjki62Kw-nSAhVY4mMKHTZuDUcQFggYMAA&url=http%3A%2F%2Framl.org%2F&usg=AFQjCNHgdH2y7WIeufmJZnvELzPW4zh0SA&sig2=aEMZhHtISM-VLiK2QfFIag&bvm=bv.150120842,d.dGc https://www.google.co.nz/url?sa=t&rct=j&q=&esrc=s&source=web..., with json schema http://json-schema.org/ http://json-schema.org/

joshuaduffy 10y ago

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.

fcanela 10y ago

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.

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