DOCSEARCHbyAlgolia
Submit Docs

Scribe API Documentation Generator

website·Indexed 34 days ago

https://scribe.knuckles.wtf/

Scribe automatically generates human-readable API documentation from your codebase. It supports Laravel (versions 3.x, 4.x, and 5.x) and Node.js (version 2.x), extracting information from docblocks, PHP 8 attributes, and configuration files to document endpoints, URL parameters, headers, and responses.

Tokens
81.5K
Snippets
421
Records
565
Agent score
65%

What's inside Scribe

  1. Overview of Scribe API documentation features

    Scribe automatically generates human-friendly API documentation from a Laravel codebase. Key capabilities include:

    • Outputs: Produces a single-page HTML document with an in-browser API tester ("Try It Out"), Postman collections, and OpenAPI specifications.
    • Automatic Extraction: Extracts request parameter details from FormRequests or validation rules and generates sample responses from Eloquent API Resources or Transformers.
    • Customization: Allows UI adjustments (text, ordering, examples), custom data extraction strategies, and the ability to statically define endpoints not present in the codebase.

  2. Overview of Scribe API documentation generator

    Scribe automatically generates human-friendly API documentation from Laravel, Lumen, or Dingo codebases. Key capabilities include:

    • Generating single-page HTML documentation with an in-browser "Try It Out" API tester.
    • Exporting Postman collections and OpenAPI specifications.
    • Extracting request parameter details from FormRequests or validation rules.
    • Generating sample responses by safely calling API endpoints or using Eloquent API Resources and Transformers.
    • Customizing the UI, extraction strategies, and adding static endpoint definitions.

  3. Overview of Scribe for Laravel

    Scribe is a tool used to generate human-friendly API documentation directly from a Laravel codebase. Key capabilities include:

    • Generating single-page HTML documentation with an in-browser API tester ("Try It Out").
    • Exporting Postman collections and OpenAPI specifications.
    • Automatic extraction of request parameters from FormRequests or validation rules.
    • Generation of sample responses by calling API endpoints or using Eloquent API Resources and Transformers.
    • Customization of the UI, data extraction strategies, and the ability to statically define endpoints not present in the codebase.

  4. Overview of Scribe API documentation generator

    Scribe automatically generates human-friendly API documentation from Laravel, Lumen, or Dingo codebases. Key capabilities include:

    • Creating single-page HTML documentation with an integrated "Try It Out" API tester.
    • Extracting body parameter details from FormRequests or validation rules.
    • Generating sample responses by safely calling API endpoints or using Transformers and Eloquent API Resources.
    • Exporting Postman collections and OpenAPI specifications.
    • Supporting custom views, UI components, and extensible strategies.
    • Allowing the static definition of endpoints that do not exist in the codebase.

  5. Overview of Scribe API documentation generator

    Scribe is a tool for generating human-friendly API documentation from a Node.js codebase. Key features include:

    • Generation of a single-page HTML document with code samples and an integrated "Try It Out" API tester.
    • Ability to safely call API endpoints to retrieve sample responses.
    • Automatic generation of Postman collections and OpenAPI specifications.
    • Support for defining extra endpoints statically that are not present in the codebase.

  6. Use Markdown and HTML in Scribe documentation

    Scribe supports Markdown and HTML in the following locations:

    • The description and introText fields in the configuration file.
    • Endpoint titles and descriptions within docblocks.
    • Group names and descriptions within docblocks (using @group).
    • Parameter descriptions within docblocks.

  7. Configure automatic response calls

    When no 2xx responses are manually defined, Scribe attempts a 'response call' by faking an HTTP request to the endpoint. By default, Scribe only makes response calls for GET endpoints and wraps them in a database transaction to prevent permanent data changes.

    Configuration for response calls is located in the apply.response_calls section of the Scribe config, where you can define safe HTTP methods, Laravel config overrides, and specific parameters to include.

  8. Understand Scribe route processing stages

    Scribe processes routes in specific stages. For each stage, the Extractor runs all configured strategies in scribe.php and merges the results. Later strategies can overwrite data from earlier ones, except for the responses stage, which is additive (all responses from all strategies are preserved).

    The processing stages are:

    • metadata: Includes title, description, groupName, groupDescription, and authentication status.
    • urlParameters
    • queryParameters
    • headers: Headers for example requests and response calls.
    • bodyParameters
    • responses: (Additive stage)
    • responseFields: Descriptions of fields in the response.

  9. Implement a custom Scribe strategy plugin

    Plugins (custom strategies) allow you to provide Scribe with additional information about your endpoints. Every plugin must extend the abstract base class Knuckles\Scribe\Extracting\Strategies\Strategy. You can use the Artisan command php artisan scribe:strategy <className> to generate a strategy skeleton automatically.
    use Knuckles\Scribe\Extracting\Strategies\Strategy;

class MyCustomStrategy extends Strategy
{
    public function __invoke($endpointData, array $routeRules): ?array
    {
        // Implementation here
    }
}

  10. Understand the Scribe documentation generation process

    When scribe:generate is executed, Scribe follows a four-step pipeline to create documentation:

    1. Route Matching: The RouteMatcher fetches application routes (Laravel/Dingo) and filters them based on configuration.
    2. Extraction: The Extractor processes routes using configured strategies to gather metadata, parameters, and sample responses.
    3. Grouping: Endpoints are grouped (via @group tags) and written to intermediate YAML files in the .scribe/endpoints directory.
    4. Output: The Writer class uses Blade templates to generate HTML, which is then copied to the static.output_path (default: public/docs). If enabled, Postman and OpenAPI files are also generated. For laravel-type docs, HTML is converted back to Blade files in resources/views/scribe.

  11. Implement a custom Scribe strategy plugin

    Plugins (custom strategies) allow you to provide Scribe with additional information about your endpoints. Every plugin must extend the base strategy class Knuckles\Scribe\Extracting\Strategies\Strategy. You can use the Artisan command php artisan scribe:strategy <className> to automatically generate a strategy class.
    use Knuckles\Camel\Extraction\ExtractedEndpointData;
use Knuckles\Scribe\Tools\DocumentationConfig;

class MyCustomStrategy extends \Knuckles\Scribe\Extracting\Strategies\Strategy
{
    public function __invoke(
        ExtractedEndpointData $endpointData,
        array $routeRules = []
    ): ?array {
        // Implementation logic here
    }
}

  12. Use the automated upgrade tool for Scribe v3

    Scribe v3 includes a CLI tool that automatically updates your configuration file and warns you about necessary manual changes. The tool creates a backup of your old configuration at config/scribe.php.bak before applying changes.
    # Preview changes without applying them
php artisan scribe:upgrade --dry-run

# Apply the upgrade
php artisan scribe:upgrade