1. I'd Rather Be Writing
2. Docs
3. Chapter 4: OpenAPI spec and generated reference docs

Document360 for API docs

Download PDF

Building an API reference documentation output directly from an OpenAPI specification is a significant technical hurdle, even for an engineering-savvy UX designer. Consequently, most technical writers use specialized tools for API reference, making the quality of the output dependent on the chosen platform. The question then becomes, which tool provides the most compelling developer experience for API reference?

In this article, I’ll evaluate Document360, including several example API documentation sites. Document360 supports your regular documentation and knowledge-base content, but also allows you to publish your API documentation, bringing all content into the same documentation portal seamlessly. For API documentation, Document360 supports REST API documentation in the form of an OpenAPI specification file that you can import, upload, or continuously pull in.

• Getting Started with API Documentation in Document360
• Document360 is mostly for publishing your API reference
• Example API documentation published with Document360
  • Quick, snappy interface
  • Endpoint organization in the sidebar
  • Parameter readability
  • Try-it and code examples pane
• Conclusion

Note: Document360 is one of the sponsors of this site.

Getting Started with API Documentation in Document360

You can add your API reference documentation to Document360 in several ways. You can upload an OpenAPI file directly (as JSON or YAML), provide a URL to your hosted specification file, integrate the file via a CI/CD flow for continuous updates, or upload a Postman Collections file.

While the platform supports these different methods, for the sake of simplicity, let’s walk through that wizard process to quickly see the output. To help users quickly explore the API documentation features, Document360 also provides a sample Petstore API file. To get started:

1. Go to Document360.com and sign up for a free trial. Follow the welcome prompts. When you reach “1. Welcome to Document360”:
   • Click the Get started button in the API documentation section.
2. **“Select a method to create an API reference”:
   • Choose Try sample pet store API file for this demo. (You could select “Upload API definition” or “Create from URL” if you have your own spec file ready.)
3. “Personalize your Knowledge Base”**:
   • Skip the “Provide your website URL (optional)” field, or add your site.
4. “Brand guidelines”**:
   • Customize the Project name as desired.
5. “Set the privacy of your documentation”:
   • Select Public for easy viewing.

After completing these steps, publish the output. Open your new site, click the API documentation button (or navigate to the relevant section), and browse the generated documentation for the sample Petstore API. The published API documentation looks as follows, with intuitive navigation and includes a Try-It pane.

Document360 is mostly for publishing your API reference

Now let’s move on to discuss another aspect of Document360. Document360 is primarily a publishing engine for already-constructed OpenAPI files. Document360 assumes that you’ve already assembled your OpenAPI specification file elsewhere and now just need to publish it. Supported file formats/versions include OpenAPI (3.1, 3.0, 2.0) and Postman Collections. Document360 requires valid syntax for import and provides error feedback but doesn’t include a built-in editor to fix invalid syntax within the platform.

After you’ve imported a valid OpenAPI file, Document360 treats the API reference as read-only from the OpenAPI spec you imported. In other words, if you want to adjust a parameter description or other content, you wouldn’t do that without Document360’s interface but would instead edit your OpenAPI specification file and then either reimport it or resync the CI/CD integration. (You can add some paragraphs within the Resource descriptions, but not for the endpoints.)

Restricting editing is likely a smart move because it avoids the complexity of authoring interfaces that try to provide a GUI for constructing the complex YAML syntax of the OpenAPI specification—which is not a small feat in UI engineering. Instead, the strength of Document360’s platform is in integrating all your documentation in one place: both your regular documentation and your API reference documentation. Publishing this information in one coherent portal helps increase the coherence and consistency of the documentation experience.

Those tools that do offer GUI-based interfaces for creating the OpenAPI specification’s syntax (like Stoplight) usually have primitive authoring/editing features for the rest of their documentation. In contrast, Document360 was built first as a documentation platform, not merely as an API publishing engine. As such, the platform has a rich feature set, including everything from AI-integrated chat, ticket deflection, documentation analytics, tags, access controls, user comments, metadata, portal design, and more.

Additionally, Document360 supports multiple versions of API documentation. In short, tech writers won’t be frustrated by the lack of more advanced authoring features as a tradeoff for API publishing.

See it in action: Watch this video to see how to publish your API documentation with Document360. The quality of your API documentation output requires you to start with the right tools.

Example API documentation published with Document360

To get a sense of Document360’s user experience of API documentation, let’s look at a few examples:

• PlainID API Documentation
• PagoNXT API Documentation
• PagoNXT API Reference
• Torq API documentation
• Fortanix API documentation
• Britive API documentation
• Rocket Chat API documentation
• Medallia API documentation
• Bloxs API documentation

In the following sections, I’ll share my observations on some of these sites.

Quick, snappy interface

Document360 pages load quickly, and the site is easy to navigate. The experience feels modern and aligned with the latest web conventions. (In contrast, many other tech comm tools tend to have an outdated experience and feel.)

To confirm the speed, I plugged about 5 different pages from the Torq API documentation into https://tools.pingdom.com, a site that measures website technical benchmarks. Each time, the “Performance Grade” was 100. In contrast, my idratherbewriting.com site, which I feel loads quickly, scored only in the mid-70’s.

Site loading speed might not ostensibly seem like a major UX factor, but it is. Consider how developers impatiently click through various documentation pages looking for answers, especially when those pages are individual endpoints. The faster the site loads, the more apt developers will be to stick within the documentation site to find information.

Endpoint organization in the sidebar

Document360’s hierarchical grouping of API endpoints in the sidebar is easy to browse, with collapsible folders that group the different endpoints based on their tags in the OpenAPI file. If you have many different groups and API endpoints, this folder-based hierarchy allows users to navigate them without feeling overwhelmed. Here’s an example from Bloxs:

Parameter readability

In the Document360 sites, the parameters are easy to read because of the collapse/expand toggles and the tree diagram lines. For example, take a look at this Body parameters section from Fortinix:

Try-it and code examples pane

Document360’s Try-it pane and code examples offer a convenient utility for developers to experiment with the API. As has come to be expected in API outputs, this interactive pane appears on the right, creating a tri-column display. Given this three-column output, there’s not a lot of extra real estate, but Document360 manages to make the UI comfortable and attractive despite the limited space. Take a look at this example from Medallia:

Here’s another example with the Rocket Chat API, this time with the Try-it pane shown by default:

See it in action: This video walks you through the concept step by step:

Overall, Document360’s API user interface is impressive and usable. It showcases your API documentation following API design best practices and standards—all with minimal fuss and configuration on your part as a writer or engineer delivering documentation.

This last part is worth emphasizing—if, as a technical writer, you find yourself spending more time fiddling with website code than your docs, more time figuring out JavaScript than on the clarity of your API’s field and parameter descriptions, more time on style libraries than on the consistency of your API endpoint descriptions, tutorials and workflows, and other documentation content, then the tradeoff for that design flexibility and customization backfires. Developers will consume content on your site; the site features and structure, nor your attention to them as an author, shouldn’t take away focus from the words on the page.

Conclusion

As I browsed through the dozen sample sites showcasing API documentation using Document360, it made me think about how the API landscape has matured. When I first created my API documentation course (back around ~ 2016), it wasn’t clear if Swagger, RAML, or Blueprint would be the dominant format. Swagger UI’s interactive “Try it!” options to execute real requests connected with the developer imagination, especially given how developers lean towards experiential, exploratory learning. Seeing code samples in a variety of languages—another common design pattern—was also compelling, along with more diagrammed views of inputs and responses, common in Redocly’s API output.

Now that at least a decade has passed, the various outputs have settled on a more or less expected feature set of API best practices and layouts. The tri-column layout, with collapsible sections, interactive explorers, and other styling (like colorful shading for operations, such as “POST”) dominate the landscape. Documentation that doesn’t have an API Explorer (e.g., “Try It!”) feature now seems incomplete.

Document360 has the benefit of coming later to the API reference documentation generation scene, as it can take advantage of these more solidified UI expectations and pull from the best of all outputs. Document360’s API documentation experience is just what any developer might expect and hope for with reference documentation. As an author, there’s no need to deliberate on design or incorporate additional features. And following industry best practices with API documentation, the user experience becomes even more familiar and intuitive.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.