undefined | Better HN

0 pointsconorgil14511y ago0 comments

Thanks for suggesting another tool to look into! I only glanced at their homepage, but it looks like they may be using Swagger under the hood because some visual elements are similar and the functionality is also similar. It does appear to have many of the features that I am looking for, so it definitely warrants further investigation.

0 comments

gkoberger11y ago

@conorgil145 (Couldn't reply; too nested)

We existed (much) after Swagger. I've never used Swagger myself, although I briefly played around with the client. Not really that inspired by them.

We use APIDoc (and eventually want to add more) as our "schema", and you can auto-sync from GitHub. Or, you can add it manually.

I am familiar with RTD (moreso the .org version than the .com); they're great. However, they mostly just host Sphinx/markdown/etc files. ReadMe does much more (support section, API explorer, "Suggest Edits", show user keys in the code, etc). If you want to write docs locally and deploy, use RTD. If you want something more full-featured, check out ReadMe.

conorgil145OP11y ago

Thanks for comparison. I have not played with either your tool nor RTD yet, but I look forward to trying both.

I came across the APIDoc project when watching an excellent presentation by the Gilt CTO titled "Immutable Infrastructure with Docker and EC2" [1]. It is worth a watch and he mentions that APIDoc allows them to more easily create new micro services in their cluster (of which they have over 300!).

I was reading around the APIDoc site and saw they had a note to investigate Swagger 2.0 to see if it could be useful [2].

[1] https://www.youtube.com/watch?v=GaHzdqFithc [2] https://github.com/gilt/apidoc/blob/master/TODO#L95

I would love to see a few projects explore this concept of generating docs, client code, and server code from a single "ground truth" file and eventually have them all merge into a single defacto standard. That would be exciting indeed (though it seems Swagger may already be approaching that point in some circles).

gkoberger11y ago

We aren't using Swagger (although we someday plan on supporting it); shoot us an email (support@readme.io) if we can help you get set up!

conorgil145OP11y ago

Thanks for the info! I have many questions about your tool, but if the answer is "go check it out via a free account!" then just tell me that and I'll get around to it :)

- Were you influenced by Swagger at all? Did you exist before/after?

- Do you expose any schema that developers can modify via an API or similar? Do you have an internal schema that all docs follow?

- I edited my original comment to include Read the Docs [1]. Are you familiar with that service (it is in private beta)? What are some advantages of using ReadMe instead of Read the Docs?

[1] http://readthedocs.com

j / k navigate · click thread line to collapse

0 comments

gkoberger11y ago

@conorgil145 (Couldn't reply; too nested)

We existed (much) after Swagger. I've never used Swagger myself, although I briefly played around with the client. Not really that inspired by them.

We use APIDoc (and eventually want to add more) as our "schema", and you can auto-sync from GitHub. Or, you can add it manually.

conorgil145OP11y ago

Thanks for comparison. I have not played with either your tool nor RTD yet, but I look forward to trying both.

I was reading around the APIDoc site and saw they had a note to investigate Swagger 2.0 to see if it could be useful [2].

[1] https://www.youtube.com/watch?v=GaHzdqFithc [2] https://github.com/gilt/apidoc/blob/master/TODO#L95

gkoberger11y ago

We aren't using Swagger (although we someday plan on supporting it); shoot us an email (support@readme.io) if we can help you get set up!

conorgil145OP11y ago

Thanks for the info! I have many questions about your tool, but if the answer is "go check it out via a free account!" then just tell me that and I'll get around to it :)

- Were you influenced by Swagger at all? Did you exist before/after?

- Do you expose any schema that developers can modify via an API or similar? Do you have an internal schema that all docs follow?

- I edited my original comment to include Read the Docs [1]. Are you familiar with that service (it is in private beta)? What are some advantages of using ReadMe instead of Read the Docs?

[1] http://readthedocs.com

j / k navigate · click thread line to collapse