juststeveking / laravel-redoc Goto Github PK

View Code? Open in Web Editor NEW

63.0 3.0 9.0 58 KB

A simple API documentation package for Laravel using OpenAPI and Redoc

License: MIT License

PHP 84.61% Blade 15.39%

laravel-redoc's Introduction

Laravel Redoc

Easily publish your API documentation using your OpenAPI document in your Laravel Application.

Installation

You can install this package via composer:

composer require juststeveking/laravel-redoc

Configuration

You can publish the configuration file with:

php artisan vendor:publish --provider="JustSteveKing\Laravel\LaravelRedoc\RedocServiceProvider" --tag="config"

This is the contents of the published config file:

return [
    'path' => [
        'name' => env('REDOC_PATH_NAME', 'docs'),
        'url' => env('REDOC_PATH_URL', 'api/docs'),
    ],

    'openapi' => [
        'path' => env('REDOC_OPENAPI_PATH', 'http://petstore.swagger.io/v2/swagger.json')
    ],

    'config' => [
        'search' => false,

        'hostname' => false,

        'loading' => false,

        'menu' => true,

        'scrollbars' => true,

        'trust' => true,
    ]
];

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

laravel-redoc's People

Stargazers

Watchers

Forkers

mikebronner johnathanmdell jeffersonsimaogoncalves sadovojav siberfx ddouble-d christogonus go24dev erayaydin sauromates

laravel-redoc's Issues

Route Middleware

First off, great package and easy to use, we prefer to have our documentation sit behind authentication, however the current set up does not allow for middleware.

I have created a pull request #6 to allow for middleware, it does have backwards compatibility with configs that may not have the path.middleware key.

Hi, thanks for creating this package. Our API is spec'd out using multiple OpenAPI files (Redoc seems to recommend this approach as well). I didn't see a way to configure that in the config, as it doesn't accept folder, but requires pointing to a OpenAPI spec file directly.

Thanks for your help, would love to be able to use your package!

Config Setting Oddity

For some reason the hostname setting only shows the hostname when set to false (boolean), but hides the hostname when set to "false" (string) as the comments suggest to use. All other config variables work with stringified booleans, which is very confusing. I just wanted to bring this up as an issue, instead of assuming how you want this fixed.

I'm happy to open a PR to bring the config values more inline with what a Laravel develop might expect, if that is something that would help you out. (For example, all the config values are inverted in their meaning, as in hostname should actually be hideHostname and be a true boolean, then handle it accordingly in the blade view to meet the redoc requirements. Just a suggestion.)

Thanks! :)

Laravel 11 Support

Are there any plan for supporting Laravel 11 with a dev branch/tag? It's not stable released but currently have some projects migrating L11.

UI Questions

Hi @JustSteveKing, we have successfully implemented our OpenAPI spec file now, and I have a few questions that I'm not sure how to address, if you don't mind?

~~Is there a way to customize the theme, say add a logo, customize colors, etc?~~
~~The search functionality doesn't seem to be working, as the search field doesn't show even if I change the config setting.~~
~~Long examples don't seem to wrap nicely, and get obscured behind the right sidebar. This may be addressable by editing the theme, per question # 1.~~
~~is automatic doc generation something that might be on the roadmap? Not required, just curios.~~

I really like you package, as it lets me create my docs using the spotlight.io GUI, and push them to my repo, and your package automatically renders it. Sweetness right there. :)

Thanks again for you time.

PS: Here's our work in progress: https://mike-b.totalitylms.com/api/docs

Updates

For things I have found answers to in the meantime, noting these here as these might help others out.

you can add a logo by adding the following to your spec file:

{
  // ..
  "info": {
    "x-logo": {
        "url": "<url to image>",
        "altText": "<your logo alt text>"
    },
    // ...
  },
  // ...
}

I realize now that things like theming and rendering, as well as automatic document generation are way out of scope of this package.
to get search to work, you must add the following to your content security policies:
```
child-src: blob:;
```
to customize the theme:
- publish this packages views: php artisan vendor:publish --provider="JustSteveKing\Laravel\LaravelRedoc\RedocServiceProvider"
- customize the doc.blade.php view. It is important to note that the theme attribute must be in single-quotes, so that the json it contains uses double-quotes, otherwise it won't render.
```
   <redoc
     theme='{"colors": {"primary": { "main": "#FF5733"}}}'
     
   ></redoc>
```
- see the following link for theming options: https://redoc.ly/docs/api-reference-docs/configuration/theming/#example-theme