README

BRJ organisation

Structured API Documentation

Fully automated tool for documentation.

📦 Installation

It's best to use Composer for installation, and you can also find the package on Packagist and GitHub.

To install, simply use the command:

$ composer require baraja-core/structured-api-doc

You can use the package manually by creating an instance of the internal classes, or register a DIC extension to link the services directly to the Nette Framework.

Idea

When developing any application, developers must maintain both the source code itself and documentation describing the general functionality for others. Writing documentation in a separate system takes more time, leads to human error, and makes the documentation obsolete over time. BRJ solves this problem by allowing developers to write documentation directly into comments in the source code, and then always machine-generate the page consistently.

How to start using BRJ documentation?

Use Structured API endpoints (implementing Baraja Structured API) to your application
Install this package
Open URL /api-documentation

Sample endpoint implementation with native comments:

/**
 * Common API endpoint for robust article manipulation.
 *
 * @endpointName Article manager
 */
final class ArticleEndpoint extends BaseEndpoint
{
   #[Inject]
   public ArticleManagerAccessor $articleManager;


   /**
    * @param string $locale in format "cs" or "en"
    * @param int $page real page number for filtering, 1 => first page ... "n" page
    * @param string|null $filterTitle filter by words in title?
    * @param string|null $filterFrom find all articles from this date
    * @param string|null $filterTo find all articles to this date
    */
   public function actionDefault(string $locale, int $page = 1, ?string $filterTitle = null, ?string $filterFrom = null, ?string $filterTo = null): void
   {
      // Here is some body...

Designed for developers

We understand that maintaining data structures in PHP and on the frontend can be challenging, so the library includes a native button to export any response structure to TypeScript:

📄 License

baraja-core/structured-api-doc is licensed under the MIT license. See the LICENSE file for more details.

baraja-core / structured-api-doc

Maintainers