Ask HN: What's the best way to write an API spec? • Hacker News Board

Re: Ask HN: What's the best way to write an API spec?

#31

Post by gdillon » Mon, Jan 19, 2015, 8:10 PM UTC

smt88 wrote: post #25

gdillon wrote: post #21

Earlier quoted context omitted.

Hey, thanks for the tip. ReadMe.io cofounder here, happy to answer any questions about my service or API specs in general. ReadMe.io currently focuses more on the "front end" of the API. We can ingest in-line comments made with the apiDoc.js [1] standard, and then use that description to build an API explorer and reference docs automatically. We like apiDoc because of how concise the comments are, and because they ar…

I like apiDoc, too, and I spent a few days adding those comments to my code. However, it's been months now, and the GitHub Sync section still says "temporarily disabled". Is this feature really done? When can I use it? I'm a bootstrapper and understand testing features by pretending they exist, but it's been a pretty long time...

Hah, touché. It's 98% done and only requires a little bit of usability polish before going live. You can shoot me a note (support [at] readme.io) with your project subdomain and I can enable it for you. Appreciate it!

Re: Ask HN: What's the best way to write an API spec?

#32

Post by bike_index » Mon, Jan 19, 2015, 8:15 PM UTC

rodw wrote: post #5

I 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 been working on updating our API to V2[1], and decided to go with grape because it automatically generates documentation via grape-swagger[2].

Initially we considered Apiary, but we wanted more flexibility and preferred to host things ourselves. And the fact that our documentation is generated automatically from the code via grape-swagger is a game changer.

[1] https://bikeindex.org/documentation/api_v2

[2] https://github.com/tim-vandecasteele/grape-swagger

Re: Ask HN: What's the best way to write an API spec?

#33

Post by dkarapetyan » Mon, Jan 19, 2015, 8:25 PM UTC

Write some client code for how you want to use the API and then elaborate those examples by making references to the spec. This might seem backwards to you but you'll discover all sorts of edge cases and awkwardness in the process that you wouldn't have discovered by just writing the spec.

You don't need any special tools to do that although apiary comes to mind as something worthwhile.

Re: Ask HN: What's the best way to write an API spec?

#34

Post by eterps » Mon, Jan 19, 2015, 8:30 PM UTC

I use Cucumber to write the API spec for our hypermedia API, it doubles as an end-to-end test which guarantees that the specs are never out of sync with our API implementation.

Re: Ask HN: What's the best way to write an API spec?

#35

Post by prabhatjha » Mon, Jan 19, 2015, 8:34 PM UTC

My vote is definitely for swagger. Besides being a great way to write API spec, it has tons of tooling to take a given spec to the next level. See the list at https://github.com/swagger-api/swagger-spec. My favorite is Swagger Editor which allows you to write a spec in YAML and shows you consumable API in real time.

There also exist an opens source project that has Swagger at its core called a127 (https://github.com/apigee-127/a127-documentation/wiki) that allows you to build enterprise-class APIs in Node.js locally and deploy to any PaaS where you can run a node app.

Disclaimer: I work with a127 project.

Re: Ask HN: What's the best way to write an API spec?

#36

Post by dreamdu5t » Mon, Jan 19, 2015, 9:02 PM UTC

Why not model your REST resources so that API documentation can be auto-generated from your actual code? Makes a lot more sense to me than trying to generate code from documentation.

Re: Ask HN: What's the best way to write an API spec?

#37

Post by mcescalante » Mon, Jan 19, 2015, 9:03 PM UTC

simi_ wrote: post #7

We tried a lot of options at Lavaboom (including apiary, readme.io, swagger, etc) and ended up using Slate: https://github.com/tripit/slate

I would also love to hear a bit more about why you guys chose Slate over the others. Working on API documentation right now for a University, and leaning towards Slate.

Re: Ask HN: What's the best way to write an API spec?

#38

Post by marcoherbst » Mon, Jan 19, 2015, 9:16 PM UTC

I can't be entirely sure that it's to do with the tools used (I'm familiar with most of the ones mentioned in the comments) but my most successful API designing, at a high level, has been in a spreadsheet.

Re: Ask HN: What's the best way to write an API spec?

#39

Post by xiaoma » Mon, Jan 19, 2015, 9:26 PM UTC

1) The best tool is probably RAML. It's very succinct, looks like YAML and has powerful features such as traits that really simplify the process of documenting many endpoints with similar traits (e.g. pagination). http://raml.org/

2) Swagger is an older option that is quite verbose but has a lot of good tooling support.

3) A third tool that is pretty decent is API blueprint.

Disclosure: I did work on an open source swagger-raml converter about four months ago.

Re: Ask HN: What's the best way to write an API spec?

#40

Post by andrewstuart » Mon, Jan 19, 2015, 9:51 PM UTC

Regardless of solution chosen, Swagger or otherwise, I'm puzzled as to why people integrate the API spec/documentation into their source code. Seems to me to provide incredible scope for bugs and dramatically increase software complexity: http://fourlightyears.blogspot.com.au/2015/01/swagger-is-gre...