DEV Community

Discussion on: What API documentation generator/tool do you use?

Collapse
texas_kristen profile image
Kristen White • Edited on

Full discloser - I work for Stoplight. I'm typically a docs consumer, not creator, so I don't have any real preference for how they're generated. All the same, as an employee I'm biased.

We've got 2 different docs options, this one is free & basic stoplight.io/docs/

If you need more theming options, this one is paid but there is a free trial stoplight.io/hubs/. Big Commerce uses this plan and they've made some pretty slick lookin' docs if I do say so myself. developer.bigcommerce.com/

Hard requirement for me is version-able documentation - you can change versions on the documentation page in case you're not up-to-date and get whatever we've set as the documentation at that version. Ideally the documentation would show a pull request-like output (red deleted, green added) between versions as well.

I like the idea of the files changed red/green view, if that isn't a capability we already have, I'm going to add it to our roadmap (anyone can add & vote for roadmap items, it's found at stoplight.io/p/roadmap.)

Update We do have versioning capabilities on our docs hubs product stoplight.io/hubs/ docs.stoplight.io/platform/version...

Thread Thread
shakesbeardz profile image
Yahia Battach

thanks for the comment, I liked what bigcommerce did with stoplight.io but I wanted to try it in stoplight.io/hubs/ but I couldn't I think you are still working on it

Thread Thread
texas_kristen profile image
Kristen White

Yeah, the version that BigCommerce started using a few years back is considered legacy now, we're rolling out the latest and greatest in mid-April. In the meantime, you can still write basic docs with stoplight.io/docs/ and the April release will include a bunch of neat features.

Thread Thread
perryloh profile image
Perry Loh

Kristen - is that new version of developer.bigcommerce.com still using Stoplight? Ie. as a customised/self-hosted enterprise version of Stoplight.

Thread Thread
texas_kristen profile image
Kristen White

I'm not in the loop about the details of their deployment, but yes, they are still using Stoplight. I'm not quite sure what you mean by new version.

Thread Thread
perryloh profile image
Perry Loh • Edited on

I mentioned new version because there was a bigcommerce.stoplight.io and just assuming that was what you pointed out as 'legacy'. I was looking at developer.bigcommerce.com and saw there were hints of stoplight in there but couldn't confirm. I was wondering if they were using a self-hosted enterprise and customizable version of Stoplight then ?
ps. full disclosure, we are a new customer on Stoplight.io, and the level of customization we have available is obviously closer to bigcommerce.stoplight.io than developer.bigcommerce.com