IPFS CLI API Docs

[jbenet]

We should have a way to generate commands + api reference markdown, so we can add it to the website easily.

[jbenet]

cc @mappum

[dborzov]

I sketched a tool for that, check it out: https://github.com/dborzov/ipfs-commands/

Here is an example of the source template file it takes. It uses go's template library markup language and just imports the command objects from github.com/core/commands.

Let me know if that could work and I will add command sorting, and subcommand traversing.

@jbenet, @mappum

[llSourcell]

really looking forward to seeing the api reference as i want to build an open source ipfs based twitter clone

[jbenet]

@dborzov very nice stuff! i'm still handling a lot of alpha stuff --will try to look at this before tue/wed.

[NodeGuy]

I want API documentation sooner. I'm currently looking at adding support for DHT commands to the Javascript library.

[jbenet]

@NodeGuy thanks for bumping. btw, the api follows the cli commands exactly, so at worst case you are free to poke at it now.

More generally, what do people think is a good http api reference format? I like the Stripe and github styles. there's http://apidocjs.com and similar services, and the more recent https://readme.io/ (check out those examples! so pretty.)

[wking]

On Wed, Apr 08, 2015 at 08:38:07PM -0700, Juan Batiz-Benet wrote:

More generally, what do people think is a good http api reference
format?

I'd outsource the human-oriented formatting and go to a
machine-parsable format like Swagger 1. There are still a few rough
edges in both the Swagger spec 2 and the default renderer [3,4], but
you can express many common scenarios with clear, concise JSON and get
a pretty UI for free :).

[jbenet]

@wking swagger looks really good.

I really like the UX of stripe's api docs -- which readme.io is modelled after. i dont know what formats they use yet, and +1 on using machine-readable formats like swagger (layer of indirection+automation \o/ ). Wonder if swagger format + stripe-like frontend would be possible? Or maybe readme.io has an open-source, machine-readable (non-lock-in) format they use?

Hey @gkoberger -- care to comment? We are an open source project and could help spread the use of readme.io. We're also very happy paying for your service (it looks great!) if it delivers value for us-- we just care that it is open (open formats, not locked in, hackable, etc).

[jbenet]

https://github.com/swagger-api/swagger-spec looks really great

[wking]

On Thu, Apr 16, 2015 at 06:27:56PM -0700, Juan Batiz-Benet wrote:

https://github.com/swagger-api/swagger-spec looks really great

Before we go down this road, I should probably list the main caveats
as I see them.

My main issue with the current spec is outlined here [1](basically
it's hard to share model-subsets between models). But we can work
around that with a bit of duplication, which is annoying but will get
us through until the JSON Schema and Swagger folks have a better
alternative.

I'm less sure about the web UI, since I find it easier to just read
the JSON ;). You can put a lot of information in your JSON spec, and
I imagine it's difficult to expose all of that in an intuitive UI.
But I haven't looked into that sort of thing, because I use Swagger so
I can avoid working with that level of UI detail ;).

So for me, these are minor issues and Swagger works great. But if you
require a completely DRY, static schema or a highly polished UI, maybe
Swagger is not quite there yet.

[RichardLitt]

Hey @gdillon, saw your post here - I've been looking over the Readme.io documentation, and all I can see as an option for importing GitHub code is a one-off gist importer. Are there any automatic tools available to integrate directly with our GitHub code, and any API doc specs we may have within it (such as Swagger, see above), and to import that directly into Readme.io? Otherwise, it looks like an entirely manual process, which is sub optimal for our code base at the moment.

[gdillon]

Hey @RichardLitt, glad to have you looking at ReadMe. I've stepped away from the company, but know there are lots of plans to support that kind of functionality. @gkoberger would be the best person for your questions, or the support@readme.io address. Best!

[gkoberger]

@RichardLitt You can use Swagger in ReadMe! Email us at support@readme.io and we'll get you hooked up with the beta.

[jbenet]

👍 for readme.io

[RichardLitt]

Thanks @gkoberger! We emailed you. I've set up a trial at https://dash.readme.io/project/ipfs-node-api, but wasn't sure how to import things directly. Would love to work with you on this.

[jbenet]

API Reference discussion moved here: ipfs-inactive/http-api-spec#1