5 ms·

Building API Docs

86 points by polyrand 5y ago

ogazitt 5y ago
Automating the generation of API docs from schema (swagger / openapi) seems as important as any GitOps practice in 2022. At Aserto, we use the readme.com github actions to automatically update our API docs (aserto.readme.io) any time a new OpenAPI spec is committed.
- gkoberger 5y ago
  Totally agree! Our mindset at ReadMe is that docs should be split into two parts... there's things automation can do better (reference guides, code samples, interactivity, etc) and things people can do better (marketing pages, tactical guides, etc). (Feel free to shoot me an email if you have any product feedback!)
mrlatinos 5y ago
Heroku's API docs made my mobile browser freeze
arcbyte 5y ago
I've never found anything better than Enunciate. Works very well and it's guaranteed always up to date because it's a compile time artifact. I really like that all the documentation and code are in one place, next to each other, and have a higher chance of being true and up to date than any other method
- mrbuzzinfrog 5y ago
  Isn't Enunciate only compatible for Java? I like that readme.com uses OpenAPI. Any other alternatives to readme.com that look promising?
  - gkoberger 5y ago
    Heya! We (ReadMe) do indeed work well with Open API specs! There's definitely alternatives if you're looking to just display docs. But we try to take it a step farther, and make APIs easy to use. We generate code samples in every language, have interactive try-it-now functionality, give you shareable links for API logs, have a nice clean `api` module in certain languages, have a mini getting started guide on each page, and more. My email is in my profile if you want to talk more! (I'd be curious about any shortcomings you've found we can help out with!)
deleted 5y ago
[deleted]
deleted 5y ago
[deleted]
mythz 5y ago
Our approach for generating API docs is generating a default UI including all the metadata that can be inferred from Typed DTOs and further enhanced with custom DTO attributes: https://docs.servicestack.net/api-explorer#api-customizations https://docs.servicestack.net/api-explorer#api-customization... But also allow users to define their own custom HTML Components for each API to provide full control to be able to include their own rich interactive content for any of their Types: https://docs.servicestack.net/api-explorer#api-docs https://docs.servicestack.net/api-explorer#api-docs That for optimal UX all gets bundled together with all the App's components into a single cached download.
deleted 5y ago
[deleted]
cplli 5y ago
I write the OpenAPI spec by hand as I haven’t found any tool to match my needs (nor is the API changing too often). And for the frontend to display the docs I couldn’t be any happier with https://stoplight.io/ https://stoplight.io/ (using their WebComponent for simplicity). I think I discovered this on the “APIs you won’t hate” podcast.
- johnx123-up 5y ago
  Did you try https://github.com/Redocly/redoc https://github.com/Redocly/redoc ?
  - cplli 5y ago
    Actually used them for a short while. I didn't like the additional step in my pipeline to build the docs, also they don't/didn't offer an interactive option. Other than that it looked pretty nice.
  - wdb 5y ago
    Vaguely, I also think it's doesn't support all OpenAPI definition features
VUETHEBROKENSYS 5y ago
faizshah 5y ago
Anyone tried rswag with rails? I’m trying it now. I’m also considering schemathesis & fastapi from python.
vrepsys 5y ago
Shameless plug: here's my indie-project that converts an OpenAPI/Swagger spec into something that aims to look like Stripe's API Reference: https://portal.dev https://portal.dev Here are a couple of example docs: https://space-api.portaldocs.dev https://space-api.portaldocs.dev (and the OpenAPI behind it: https://github.com/portaldev/nasa-apod-api-docs/blob/main/openapi.yaml https://github.com/portaldev/nasa-apod-api-docs/blob/main/op...) https://recur-api-beta.portaldocs.dev https://recur-api-beta.portaldocs.dev At my previous workplace we've built the whole docs portal (including the API reference) as a custom static website with Contentful (a json CMS) underneath. It was a real pain in the ass to edit and maintain, that's how I got the idea.
- wdb 5y ago
  I wish there was an open-source solution something like this or similar to Readme.com but better than Redocly
  - vrepsys 5y ago
    I'm considering of making the OpenAPI->API Reference converter an Open Source project, and then charging only if you need advanced features, like wysiwyg/inline editing, change approvals, automatic testing of the examples in the docs etc. It's just that I'm not sure I can do it until I have these advanced features. If I can't make money out of this I have to return to my day job, and stop developing portal.dev.
- atombender 5y ago
  This looks great. But I wish there were a self-hosted version. I work on a project that could use this, but it would really need to be tightly integrated with our existing hosting, I think.
  - vrepsys 5y ago
    Appreciate the feedback. Would it work for you if you could export this as a static website that you could run on your own servers? (you could do that in a Github action), or, alternatively, use some sort of React component that renders the API docs in your app?

86 points by polyrand 5y ago

Automating the generation of API docs from schema (swagger / openapi) seems as important as any GitOps practice in 2022. At Aserto, we use the readme.com github actions to automatically update our API docs (aserto.readme.io) any time a new OpenAPI spec is committed.

gkoberger 5y ago
Totally agree! Our mindset at ReadMe is that docs should be split into two parts... there's things automation can do better (reference guides, code samples, interactivity, etc) and things people can do better (marketing pages, tactical guides, etc). (Feel free to shoot me an email if you have any product feedback!)

mrlatinos 5y ago

Heroku's API docs made my mobile browser freeze

arcbyte 5y ago

I've never found anything better than Enunciate. Works very well and it's guaranteed always up to date because it's a compile time artifact. I really like that all the documentation and code are in one place, next to each other, and have a higher chance of being true and up to date than any other method

mrbuzzinfrog 5y ago
Isn't Enunciate only compatible for Java? I like that readme.com uses OpenAPI. Any other alternatives to readme.com that look promising?
- gkoberger 5y ago
  Heya! We (ReadMe) do indeed work well with Open API specs! There's definitely alternatives if you're looking to just display docs. But we try to take it a step farther, and make APIs easy to use. We generate code samples in every language, have interactive try-it-now functionality, give you shareable links for API logs, have a nice clean `api` module in certain languages, have a mini getting started guide on each page, and more. My email is in my profile if you want to talk more! (I'd be curious about any shortcomings you've found we can help out with!)

deleted 5y ago

[deleted]

deleted 5y ago

[deleted]

mythz 5y ago

Our approach for generating API docs is generating a default UI including all the metadata that can be inferred from Typed DTOs and further enhanced with custom DTO attributes: https://docs.servicestack.net/api-explorer#api-customizations https://docs.servicestack.net/api-explorer#api-customization... But also allow users to define their own custom HTML Components for each API to provide full control to be able to include their own rich interactive content for any of their Types: https://docs.servicestack.net/api-explorer#api-docs https://docs.servicestack.net/api-explorer#api-docs That for optimal UX all gets bundled together with all the App's components into a single cached download.

deleted 5y ago

[deleted]

cplli 5y ago

I write the OpenAPI spec by hand as I haven’t found any tool to match my needs (nor is the API changing too often). And for the frontend to display the docs I couldn’t be any happier with https://stoplight.io/ https://stoplight.io/ (using their WebComponent for simplicity). I think I discovered this on the “APIs you won’t hate” podcast.

johnx123-up 5y ago
Did you try https://github.com/Redocly/redoc https://github.com/Redocly/redoc ?
- cplli 5y ago
  Actually used them for a short while. I didn't like the additional step in my pipeline to build the docs, also they don't/didn't offer an interactive option. Other than that it looked pretty nice.
- wdb 5y ago
  Vaguely, I also think it's doesn't support all OpenAPI definition features

VUETHEBROKENSYS 5y ago

faizshah 5y ago

Anyone tried rswag with rails? I’m trying it now. I’m also considering schemathesis & fastapi from python.

vrepsys 5y ago

Shameless plug: here's my indie-project that converts an OpenAPI/Swagger spec into something that aims to look like Stripe's API Reference: https://portal.dev https://portal.dev Here are a couple of example docs: https://space-api.portaldocs.dev https://space-api.portaldocs.dev (and the OpenAPI behind it: https://github.com/portaldev/nasa-apod-api-docs/blob/main/openapi.yaml https://github.com/portaldev/nasa-apod-api-docs/blob/main/op...) https://recur-api-beta.portaldocs.dev https://recur-api-beta.portaldocs.dev At my previous workplace we've built the whole docs portal (including the API reference) as a custom static website with Contentful (a json CMS) underneath. It was a real pain in the ass to edit and maintain, that's how I got the idea.

wdb 5y ago
I wish there was an open-source solution something like this or similar to Readme.com but better than Redocly
- vrepsys 5y ago
  I'm considering of making the OpenAPI->API Reference converter an Open Source project, and then charging only if you need advanced features, like wysiwyg/inline editing, change approvals, automatic testing of the examples in the docs etc. It's just that I'm not sure I can do it until I have these advanced features. If I can't make money out of this I have to return to my day job, and stop developing portal.dev.
atombender 5y ago
This looks great. But I wish there were a self-hosted version. I work on a project that could use this, but it would really need to be tightly integrated with our existing hosting, I think.
- vrepsys 5y ago
  Appreciate the feedback. Would it work for you if you could export this as a static website that you could run on your own servers? (you could do that in a Github action), or, alternatively, use some sort of React component that renders the API docs in your app?