I'm working on a project that contains a REST API, and I want to write out a spec before I start. Are there tools for this, or should I just make a Google Docs table for it or something?
Ask HN: What's the best way to write an API spec?
1–10 of 58 posts
Re: Ask HN: What's the best way to write an API spec?
#2Writing tests for your spec is probably the best way. You get to test the design of your API (and any edge cases/scaling issues) before you actually have to design it, and, bonus, when you're done you have a full suite of tests.
Re: Ask HN: What's the best way to write an API spec?
#3Have a look at http://apiary.io and http://readme.io
Re: Ask HN: What's the best way to write an API spec?
#4You may find my comment in a related thread interesting: https://news.ycombinator.com/item?id=8847072
I was discussing my interest in documenting an API and then generating client libraries, API tests, and other artifacts automatically. Some relevant tools and projects were mentioned/discussed.
Re: Ask HN: What's the best way to write an API spec?
#5I guess I'll take this opportunity to plug my own little tool for this.
I use Swagger [1] and more specifically Swagger UI [2] to generate interactive web-based documentation like the sample at [3].
But rather than relying upon source code annotations to have swagger auto-generate the documentation, or hand-writing swagger's verbose JSON structure, I created a little DSL for it as demonstrated at [4] and available on GitHub at [5].
Let me know if you have any questions about swagger-dsl. It's under-documented right now but perfectly functional. I use it often.
[2] https://github.com/swagger-api/swagger-ui
[3] http://petstore.swagger.wordnik.com/#!/pet
Re: Ask HN: What's the best way to write an API spec?
#6use something like capybara or Rspec Testing (rails ) to stimulate a real user behavior
Re: Ask HN: What's the best way to write an API spec?
#7We tried a lot of options at Lavaboom (including apiary, readme.io, swagger, etc) and ended up using Slate: https://github.com/tripit/slate
Re: Ask HN: What's the best way to write an API spec?
#8There have been an explosion of API specification formats in the last few years. No clear winner has emerged.
JSON Schema and JSON Hyperschema are JSON-based formats for describing JSON and REST (hypermedia-driven) APIs. The formats make decent sense and can be used to generate docs, validators, client libraries, UIs, and more. http://json-schema.org/
API Blueprint is another emerging format for API description. It's written in Markdown, so it is very human-readable and -writable. It is not yet suitable for hypermedia APIs. Like JSON Schema, its tooling includes validators, client library generators, mock server generators, docs generators, etc. http://apiblueprint.org/
Swagger is a YAML-based format for specifying JSON APIs. It is meant to be created using the Swagger UI, rather than handwritten. It generates pretty docs, client software, etc. but is not suited to describing hypermedia APIs. http://swagger.io
Slate is an API documentation framework/template, designed to generate very handsome documentation pages. Its concern is more documentation than specification, and therefore doesn't concern itself with things like library or mock generation. https://github.com/tripit/slate
WADL is an API description language which describes API interactions in an XML format. It resembles WSDL. Not many people use it. http://en.wikipedia.org/wiki/Web_Application_Description_Lan...
Which of these is the best? Good question. I like JSON Hyperschema, but I am writing hypermedia APIs and the other formats here are lacking in their hypermedia support. API Blueprint is a nice format to write in a text editor and is easily read as-is or rendered from Markdown; no separate docs generator is necessary.
Re: Ask HN: What's the best way to write an API spec?
#9There have been an explosion of API specification formats in the last few years. No clear winner has emerged. JSON Schema and JSON Hyperschema are JSON-based formats for describing JSON and REST (hypermedia-driven) APIs. The formats make decent sense and can be used to generate docs, validators, client libraries, UIs, and more. http://json-schema.org/ API Blueprint is another emerging format for API description. It's…
Yet another relatively new definition format: http://raml.org/
Re: Ask HN: What's the best way to write an API spec?
#10I guess I'll take this opportunity to plug my own little tool for this. I use Swagger [1] and more specifically Swagger UI [2] to generate interactive web-based documentation like the sample at [3]. But rather than relying upon source code annotations to have swagger auto-generate the documentation, or hand-writing swagger's verbose JSON structure, I created a little DSL for it as demonstrated at [4] and available on…
We've (Workday) started using this internally and love it. Thankyou!