Generate API documentation for humans from your Laravel codebase.✍

Related tags

Miscellaneous scribe
Overview

Scribe

Latest Stable Version Total Downloads


v3 is out now!

Scribe helps you generate API documentation for humans from your Laravel/Lumen/Dingo codebase. See a live example at demo.scribe.knuckles.wtf. There's a Node.js version, too!

Features

  • Pretty single-page HTML doc, with human-friendly text, code samples, and included in-browser API tester ("Try It Out")
  • Extracts body parameters details from FormRequests or validation rules
  • Safely calls API endpoints to get sample responses
  • Supports generating responses from Transformers or Eloquent API Resources
  • Generates Postman collection and OpenAPI spec
  • Easily customisable with custom views and included UI components
  • Easily extensible with custom strategies
  • Statically define extra endpoints that aren't in your codebase

👋 Scribe helps you generate docs automatically, but if you really want to make friendly, maintainable and testable API docs, there's some more things you need to know. So I made a course for you. 🤗

Documentation

Check out the documentation at scribe.knuckles.wtf/laravel.

v2 docs (PHP 7.2+, not actively maintained) are at scribe.rtfd.io.

If you're coming from mpociot/laravel-apidoc-generator, there's a migration guide.

Contributing

Contributing is easy! See our contribution guide.

Comments
  • OpenAPI: Set properties of objects nested in arrays

    OpenAPI: Set properties of objects nested in arrays

    When generating the documentation, the OpenAPI does not include properties of objects that are nested in arrays. This PR aims at fixing this bug.

    Before:
    openapi: 3.0.3
    info:
      title: 'Test'
      version: 1.0.0
    paths:
      /api/test:
        get:
          responses:
            '200':
              description: Successful response
              content:
                application/json:
                  schema:
                    type: object
                    example:
                      someArray:
                        - anotherObjectKey: objectValue
                    properties:
                      someArray:
                        type: array
                        example:
                          anotherObjectKey: objectValue
                        items:
                          type: object
    
    After:
    openapi: 3.0.3
    info:
      title: 'Test'
      version: 1.0.0
    paths:
      /api/test:
        get:
          responses:
            '200':
              description: Successful response
              content:
                application/json:
                  schema:
                    type: object
                    example:
                      someArray:
                        - anotherObjectKey: objectValue
                    properties:
                      someArray:
                        type: array
                        example:
                          anotherObjectKey: objectValue
                        items:
                          type: object
                          properties:
                            anotherObjectKey:
                              type: string
                              example: objectValue
    
    Diff:
    --- a/before
    +++ b/after
    @@ -22,3 +22,7 @@ paths:
                           anotherObjectKey: objectValue
                         items:
                           type: object
    +                      properties:
    +                        anotherObjectKey:
    +                          type: string
    +                          example: objectValue
    
    opened by Floppy012 0
  • Bug in using an image

    Bug in using an image

    hello I want to make the doc for a route who has to send an image

    But no matter if I put the image in img/logos/logo. png or in ressources/images/logo. png I have the second screenshot exception

    Did I use wrong? I don't see my mistake in the doc

    Thx for all

    Screenshots and stack traces: image image

    My environment:

    • PHP version 8.1.13 : - Framework (Laravel):
    • Laravel versions : * v9.46.0
    • Scribe versions : * 4.10.1

    **My Scribe config : PHP Warning: PHP Startup: gd: Unable to initialize module Module compiled with module API=20190902 PHP compiled with module API=20210902 These options need to match

    Warning: PHP Startup: gd: Unable to initialize module Module compiled with module API=20190902 PHP compiled with module API=20210902 These options need to match in Unknown on line 0 title => "Seela API Documentation" base_url => "http://127.0.0.1:8000" try_it_out.base_url => "http://127.0.0.1:8000" auth.enabled => true auth.default => true auth.name => "Authorization" auth.use_value => "[email protected]" logo => "img/logos/logo.png" last_updated => "Last updated: {date:j F Y}"

    bug 
    opened by tlinossier 1
  • Double curly brackets in API response break scribe blade template

    Double curly brackets in API response break scribe blade template

    Hi I have json response from my API containing string like "This field must be {{value}} or less" and looks like this breaks scribe's blade, because I get an error:

    "Error PHP 8.2.0. 9.45.1 Undefined constant "value""

    Looks like scribe inserts response from API right into blade without escaping double curly brackets {{ ? And laravel then tries to parse {{value}} in blade and can't find such constant? Maybe I can make scribe encode {{ in output from my API?

    Thanks

    bug help wanted 
    opened by alexweb 1
  • Scribe's auto detected ID parameter name is always `id`

    Scribe's auto detected ID parameter name is always `id`

    What happened?

    1. I ran php artisan scribe:generate
    2. And I saw scribe auto generated id urlParam for /class/{class_room}/opening-hours/{opening_hour}

    I cannot change id to opening_hour, whenever i add @urlParam opening_hour scribe creates documentation with three url parameters.

    Screenshots and stack traces: Route Handler php artisan route:list result: GET|HEAD class/{class_room}/opening-hours/{opening_hour} ..... admin.class.room.opening-hours.show Scribe Result

    My environment:

    • PHP version (from php -v): 8.1.3
    • Framework (Laravel/Lumen): Laravel
    • Laravel/Lumen version (from composer show laravel/framework or composer show laravel/lumen-framework): v9.46
    • Scribe version (from composer show knuckleswtf/scribe): 4.10.1

    My Scribe config (from php artisan scribe:config:diff):

    title => "Test"
    base_url => "https://www.test.test"
    type => "laravel"
    laravel.add_routes => false
    try_it_out.base_url => "https://www.test.test"
    auth.enabled => true
    auth.default => true
    auth.placeholder => "{YOUR_PERSONAL_AUTH_TOKEN}"
    strategies.metadata => removed Knuckles\Scribe\Extracting\Strategies\Metadata\GetFromMetadataAttributes
    strategies.urlParameters => removed Knuckles\Scribe\Extracting\Strategies\UrlParameters\GetFromUrlParamAttribute
    strategies.queryParameters => removed Knuckles\Scribe\Extracting\Strategies\QueryParameters\GetFromQueryParamAttribute
    strategies.headers => removed Knuckles\Scribe\Extracting\Strategies\Headers\GetFromHeaderAttribute
    strategies.bodyParameters => removed Knuckles\Scribe\Extracting\Strategies\BodyParameters\GetFromBodyParamAttribute
    strategies.responses => removed Knuckles\Scribe\Extracting\Strategies\Responses\UseResponseAttributes
    strategies.responseFields => removed Knuckles\Scribe\Extracting\Strategies\ResponseFields\GetFromResponseFieldAttribute
    

    Additional info: I need to be able to disable automatic ID detection or rename it to what i want or whatever it actually is, at least. It should be opening_hour in my route, not id.

    bug 
    opened by Allgoodnamesargone 1
  • Generate Response Fields from @apiResource or #[ResponseFromApiResource]

    Generate Response Fields from @apiResource or #[ResponseFromApiResource]

    • [x] I've read the documentation and I can't find details on how to achieve this.
    • [x] I almost know the section Responses by heart

    I very much like the option to autogenerate an example response from a given API Resources and Models because it reduces code duplicity. But I would love if scribe would generate ResponseField (with name and type) from the API Resource / the Model (instead of just example responses).

    In the following I describe an excerpt of my results so far and how I would like them to be:

    • I have
      • a model called Rating,
      • a route GET api/ratings and
      • a Controller Method RatingController::all() where a ResourceCollection (RatingCollection::class) is returned.
    <?php
    ...
    /**
     * Class Rating
     * 
     * @property int $id
     * @property Carbon|null $created_at
     * @property Carbon|null $updated_at
     * @property int $score
     * @property int $userID
     * @property int $bikeID
     * 
     * @property Bike $bike
     * @property User $user
     *
     * @package App\Models
     */
    class Rating extends BaseModel
    {
    	protected $table = 'ratings';
    
    	protected $casts = [
    		'score' => 'int',
    		'userID' => 'int',
    		'bikeID' => 'int'
    	];
    
    	protected $fillable = [
    		'score',
    		'userID',
    		'bikeID'
    	];
    
    	public function bike()
    	{
    		return $this->belongsTo(Bike::class, 'bikeID');
    	}
    
    	public function user()
    	{
    		return $this->belongsTo(User::class, 'userID');
    	}
    }
    
    Route::get("ratings", [RatingController::class, 'all'])->name('ratings.get');
    
    /**
     * @group Ratings 
     * API to create or update and read bike ratings
     */
    class RatingController extends Controller
    {
        /**
         * GET ratings
         * 
         * user sees a list of all ratings for all bikes (since a certain time)
         */
        #[QueryParam('sinceDate', 'date', 'time from which the ratings were submitted', required: false, example: '2023-04-26T12:30:00')]
        #[ResponseFromApiResource(RatingCollection::class, Rating::class)]
        public function all(FormRequests\Rating\GetAllRequest $request)
        {
            $validated = $request->validated();
            $ratings = Rating::where('updated_at', '>=', date("Y-m-d H:i:s", strtotime($validated['sinceDate'])))->get();
            return new JsonResponse(new RatingCollection($ratings), 200, [], 0);
        }
    }
    

    I get the following result: Screenshot 2023-01-04 at 01 14 59

    I would love this result (without manually adding ResponseFields): Screenshot 2023-01-04 at 01 22 12

    question 
    opened by marfrede 2
  • Url parameter access on formRequest does not work

    Url parameter access on formRequest does not work

    Hello,

    In a FormRequest, access directly to url parameter does not work (null). Here is a code example:

    <?php
    
    namespace App\Http\Requests;
    
    use Illuminate\Foundation\Http\FormRequest;
    use Illuminate\Support\Facades\Route;
    
    class UserRequest extends FormRequest
    {
    
        public function rules(): array
        {
            $this->user; // null
    
            $this->route('user'); // null
    
            Route::current()->parameters()['user']; // not null
    
        }
    }
    

    Only the third one works but i prefer to avoid this.

    I ran php artisan scribe:generate

    bug 
    opened by oskobri 0
Releases(4.10.1)
Text formatting for humans.

Deutsch English Svenska Markdown 0.8.22 Text formatting for humans. How to format text Markdown is a practical way to edit web pages. Write text like

Anna 2 Nov 3, 2022
This repository contains the codebase PHP bridge using RoadRunner Jobs plugin.

RoadRunner Jobs Plugin This repository contains the codebase PHP bridge using RoadRunner Jobs plugin. Installation To install application server and J

Spiral Scout 15 Nov 9, 2022
PhpCodeAnalyzer scans codebase and analyzes which non-built-in php extensions used

PhpCodeAnalyzer PhpCodeAnalyzer finds usage of different non-built-in extensions in your php code. This tool helps you understand how transportable yo

Sergey 92 Oct 19, 2022
Official OpenMage LTS codebase | Migrate easily from Magento Community Edition in minutes

Official OpenMage LTS codebase | Migrate easily from Magento Community Edition in minutes! Download the source code for free or contribute to OpenMage LTS | Security vulnerability patches, bug fixes, performance improvements and more.

OpenMage 782 Jan 3, 2023
PhpCodeAnalyzer scans codebase and analyzes which non-built-in php extensions used

PhpCodeAnalyzer PhpCodeAnalyzer finds usage of different non-built-in extensions in your php code. This tool helps you understand how transportable yo

Sergey 89 Jan 14, 2022
Testing your OpenApi documentation and your code easily.

Raven - How to test your API documentation and behavior. This library was written to allow testing OpenAPI documentation easily. It also allows verify

CH Studio 30 Dec 6, 2022
A list of documentation and example code to access the University of Florida's public (undocumented) API

uf_api A list of documentation and example code to access the University of Florida's public (undocumented) API Courses Gym Common Data (admissions an

Rob Olsthoorn 49 Oct 6, 2022
Simple IT Documentation Solution for MSPs

SimpleMSPDoc RC 1.0 I wasn't happy with what other IT documention software had. I felt they over complicated things and required so much clicky clicky

null 4 Jun 5, 2022
Disclaimer: The documentation of this plugin is English at the moment, but I might go for Latin later down the line, just for the fun of it.

Quiritibus Plugin This repository is storing the custom plugin developed for the Quiritibus Latin Magazine website, currently being developed at: http

Alkor András 1 Jan 19, 2022
Documentation on clean coding and demonstration of studied clean coding principals with PHP.

practice-php-clean-code Documentation on clean coding and demonstration of studied clean coding principals with PHP. The document contained in this re

Ferdous Islam 1 Feb 21, 2022
A Laravel Wrapper for the Binance API. Now easily connect and consume the Binance Public & Private API in your Laravel apps without any hassle.

This package provides a Laravel Wrapper for the Binance API and allows you to easily communicate with it. Important Note This package is in early deve

Moinuddin S. Khaja 7 Dec 7, 2022
#️⃣ Generate, Save, and Route Stripe-like Hash IDs for Laravel Eloquent Models

Using this package you can generate, save and, route Stripe-like Hash Ids for your Eloquent Models. Hash Ids are short, unique, and non-sequential, an

Yunus Emre Deligöz 88 Dec 27, 2022
Optional package for Laravel to generate social share links.

Laravel Share Share links exist on almost every page in every project, creating the code for these share links over and over again can be a pain in th

Joren Van Hocht 466 Dec 21, 2022
Laravel package allows you to generate a YouTube player from a video link.

Youtube Frame Generator Laravel package allows you to generate an iframe tag with a video player depending on a youtube URL. 1 - Dependency The first

Syrian Open Source 17 Nov 2, 2022
This module adds a command to easily generate "modules" in Laravel and install them using composer.

Laravel Module Create This module adds a command to easily generate "modules" in Laravel and install them using composer Installation Simply install t

null 2 Feb 18, 2022
Laravel package to generate sweepstakes using the Round Robin algorithm

Laravel package to generate sweepstakes using the Round Robin algorithm. Supports any number of teams, as long as they are greater than a minimum value specified in the configuration file. Built with Laravel Collections for better handling of arrays.

TonyStore 6 Aug 3, 2022
A simple helper to generate and display pagination navigation links

Intro to CHocoCode Paginator Friendly PHP paginator to paginate everything This package introduces a different way of pagination handling. You can rea

faso-dev 3 Aug 24, 2021
CC [CREDIT CARD] GENERATE & VALIDATE TOOL !

⚡ CCE THIS TOOL PERMIT YOU TO GENERATE CREDIT CARD & VALIDATE

BASILEOLUS 2 Sep 19, 2021
Generate stubs for any PHP extension.

php-ext-stubs-generator Installation Run $ composer require --dev lctrs/php-ext-stubs-generator Usage $ php vendor/bin/generate-stubs-for-ext extensio

null 5 Dec 14, 2022