Having useful documentation is important. But let’s face it: writing documentation isn’t exactly a developer’s favorite activity. It is often time-consuming and tedious process involving manual updates across different formats or platforms. This can lead to:

• Outdated Documentation: When updates to the API are made, the documentation often lags behind, creating confusion and frustration for developers.
• Inconsistent Style: Manually written documentation can lack a cohesive style and voice, making it less user-friendly.
• Incomplete Information: Key details like usage examples, error handling, or cross-references between endpoints might be absent.

Can we do better then ? I think we can:

Schema-driven approach

The key to good documentation is generate it based on schema or code, with the former way having more advantages in the long run.

• Reduced Documentation Effort: Developers can focus on their core tasks while the generator handles the documentation burden.
• Consistent and Up-to-Date Docs: Changes to the API schema automatically update the documentation, ensuring consistent and accurate information.
• Improved Readability: Documentation generators often produce well-formatted and easy-to-read output.

What problems are we solving ?

Customization. API documentation is usually a part of bigger developer portals, which includes human-written guides, tutorials and examples of usage. Therefore, the documentation must allow either easy embedding itself to a larger portal, or easy embedding additional content to itself.

Usability. Many documentation generators fall short by omitting essential features that developers rely on for efficient API interaction. These missing elements include:

• Search Functionality: The ability to quickly locate specific endpoints, data models, or concepts within the documentation is crucial. Searching empowers developers to find the information they need promptly.
• Usage Examples: Clear and concise code examples demonstrating how to use different API endpoints in various programming languages are invaluable for developers. They provide practical guidance on integrating the API into their applications.
• Cross-References: Developers often need to understand the relationships between different parts of the API. Comprehensive cross-referencing capabilities are essential. This includes:
• Resource Usage: For a given operation, the ability to identify which resources (entities) are involved.
• Operation Usage: For a given resource, the ability to see which API operations create, read, update, or delete it.
• Change Logs: Keeping track of API changes is vital. Detailed changelogs document API updates (new endpoints, parameter changes, etc.), allowing developers to stay informed and adapt their code accordingly.

Customization

Configuration

Template

Usability

Internationalization

API Genie supports multi-language documentation out of the box. Here’s a step-by-step guide on how to generate one:

1. Extract Texts for Translation:

Run the apigenie i18n Command: First, you’ll need to extract all translatable text strings from your OpenAPI schema. Open a terminal window and navigate to your project directory where the OpenAPI schema resides. Then, execute the following command:

apigenie i18n my-openapi-schema.yaml -o translations.pl.json

The apigenie i18n command will generate a JSON or YAML file containing all the text elements identified for translation. This file uses a specific format, where each key is a JSON Pointer referencing the specific location of the text string within your OpenAPI schema. The corresponding value is the original text that needs to be translated.

{
  "$/paths/users/get/summary": "Get User Details",
  "$/paths/users~1{userId}/get/summary": "Get User by ID",
  // ... more key-value pairs ...
}

2. Translate the Extracted Text:

Each translator will receive the translations.json file and replace the original values (e.g., “Get User Details”) with their translated equivalents in their respective language.

3. Generating Multilingual Documentation:

Generate Documentation with Language Files: Now, when generating your API documentation with API Genie, you can specify these translated files. Use the apigenie generate doc html command with the --i18n flag to include them:

apigenie generate doc html --i18n en=translations_en.json --i18n fr=translations_fr.json

In this example, en and fr represent the language identifiers for English and French, respectively. You can specify multiple languages with additional --i18n flags.

By following these steps, API Genie will generate your API documentation in the specified languages, making it accessible to a wider developer audience.