Introduction

In today's API-driven world, clear and concise documentation is essential. However, traditional tools often rely on complex formats like JSON or YAML, making them cumbersome and developer-unfriendly. I developed Apidoc, a Golang package, as a refreshing alternative, designed with human-friendliness and versatility in mind.

Why Not OpenApi?

Apidoc was born out of frustration with the limitations of existing documentation tools, particularly OpenAPI. Unlike OpenAPI, which is primarily designed for REST APIs, Apidoc offers a more flexible and adaptable approach. Apidoc can be used to document any API paradigm (including REST).

OpenAPI's JSON-based approach to API documentation becomes increasingly unfriendly as the API grows in size. The lack of comments within JSON makes it challenging to understand the intent behind specific data elements. While indentation is important for readability, it's not strictly enforced in JSON, debugging a massive unformatted JSON is horrible. Writing API documentation by hand, especially for examples with source code and larger texts, is frustrating and prone to errors. Typos, inconsistencies, and formatting issues, makes it difficult to maintain accurate and reliable documentation. Unconventional schema decisions, such as using "+" instead of "-" for unordered lists, waste time searching for solutions. All this leads to confusion, frustration, and potential bugs in the API implementation.

Why Apidoc?

• Human-Centered Focus: Unlike tools focused on machine-readable formats, Apidoc prioritizes human understanding. Apidoc strives to make documentation clear and easy to navigate for developers.
• No External Dependencies: Apidoc is self-contained, eliminating the need for additional tools or libraries.
• Modular Structure: Apidoc utilizes a block-based system, allowing you to organize your content into sections, groups, and endpoints.
• Detailed Endpoint Schemas: Get a clear picture of each endpoint with Apidoc's dedicated endpoint block, which allows you to define parameters, responses, and even include code examples.
• Versatile Support: Apidoc isn't limited to REST APIs. It can document any API paradigm, including custom protocols and APIs that don't rely on HTTP status codes.

Key Features

• Declarative Approach: Define your documentation directly in code, eliminating the need for complex JSON or YAML files.
• Built-in Web Handler: Serve your documentation directly from your API server using Apidoc's integrated web handler.
• Stylish and Responsive: Apidoc leverages Bootstrap and HighlightJS for a visually appealing and user-friendly experience.
• Theme Support: Choose from a variety of light and dark themes thanks to Bootswatch to match your preferences or branding.
• Logo Support: Easily set your logo to completely brand the documentation as your own.

A Glimpse into Apidoc

doc := apidoc.NewDocumentation().
  SetTitle("Example API Documentation").
  SetHomeURL("https://yourwebsite.com").
  SetDescription("This is an example API documentation for demo.").
  SetLogo(`https://yourwebsite.com/yourlogo.jpg`)
  AddBlock(sectionVersion()).
  AddBlock(sectionContact()).
  AddBlock(sectionLicense()).
  AddBlock(groupAuthentication()).
  AddBlock(groupEndpoints())

Experience Apidoc Today

To see Apidoc in action, I have prepared a small demo. To visit the demo click the link here. The link should open in a new window.

This interactive demonstration showcases the capabilities of Apidoc, allowing you to explore the documentation structure, navigate through sections and endpoints, and view code examples. By experiencing Apidoc firsthand, you can gain a better understanding of its benefits and how it can streamline your API documentation process.

Join the Apidoc Community

Apidoc is an open-source project that welcomes contributions. If you have Golang skills and want to improve the API documentation code, make the UI more responsive, or report a bug, you are welcome to contribute to the effort. Fork the repo, create a branch, make changes, and submit a pull request. Visit our GitHub repository to get started: https://github.com/gouniverse/apidoc

Conclusion

Apidoc offers a refreshing alternative to traditional API documentation tools. Its human-friendly approach, versatility, and ease of use make it a valuable asset for developers and teams of all sizes. As the developer of Apidoc, I am confident that it can significantly improve your API documentation workflow. By adopting Apidoc, you can create clear, concise, and maintainable documentation that enhances the value of your APIs.