Api Documentation for routes

[Thavarajan]

A awesome tool pack for API, do you have any plan to implement API documentation like (swagger)

[dehboris]

Hey, @Thavarajan
You can look this package L5 Swagger that allow you to document an API

[alexzarbn]

Hi @Thavarajan,

Thank you ~

If this is something that developers would want to have, then yes, sure. But until there is no demand for that feature - no.

I will keep this issue open to see, if more developers need this.

[okaufmann]

I'm currently using orion with https://github.com/knuckleswtf/scribe which also generates an open API file which can be openend in any swagger ui instance. It also provides a postman collection.

[onlime]

I'm currently using orion with https://github.com/knuckleswtf/scribe which also generates an open API file which can be openend in any swagger ui instance. It also provides a postman collection.

@okaufmann I don't quite get it how you manage to write API documentation for individual endpoints which are all provided by Orion. As I understood Scribe, it just parses annotations - but where to put them? Or do you manually edit the Scribe generated OpenAPI file prior to feeding it into Swagger? pls explain in more detail.

@alexzarbn I am definitely interested. That's a must for our project as we want to offer the full backend API to our customers (via Sanctum tokens), so it must get documented. This was the first thing I was worried about when I stumbled upon your great project: "wow, so much magic behind the scenes, great! But how could I generate an API documentation from this?". I did not start yet with Orion but would definitely like to use it once I find a solution for this.

[patryyyck]

Hello,

Laravel-Orion is awesome.
Just a little thing is missing.... the API documentation ;-)
Great job!

[alexzarbn]

A highly anticipated feature it is, I sense...
It on top of the backlog I will put.

[Thavarajan]

If it's done trust me, this is going to be a favourite of most for the API developers

[Patrikgrinsvall]

The solution to this is:

composer require --dev knuckleswtf/scribe
php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-config

check through config in config/scribe.php
read docs at: (https://scribe.readthedocs.io/en/latest/guide-getting-started.html)

Edit: I read to late its already being worked on by the devs? Then that is most likley worth waiting for. :)

[alexzarbn]

The feature is now available as part of the v2.0 release 🎉

[alireza2281]

Hi thanks for your hard work after updating from version 1 to 2 completely when i run the command
php artisan orion:specs
i got this error:
Return value of Orion\Specs\Builders\PathsBuilder::resolveRoute() must be an instance of Illuminate\Routing\Route, null returned
and the $operationName passed to the function resolveRoute is search
what am i doing wrong?

and i have another question is this package compatible with nwidart laravel module?

[alexzarbn]

Hi @alireza2281,

Could you please check, if you are running v2.0.0 or v2.0.1? The later one contains a fix for the missing search method.

As for the compatibility with nwidart - not sure, haven't tested that. As long as the controllers and routes are defined correctly, I think it should work - it is not different from the standard resource routes implementation that Laravel has out-of-the box.

[alireza2281]

@alexzarbn

Yeah it's on v2.0.1. if you need more information, tell me to comment for you

[alexzarbn]

@alireza2281

• Please share the contents of api.php
• Are you using a different namespace for controllers (something other than App\Http\Controllers)?

[alireza2281]

@alexzarbn

I am using nwidart and i have multiple modules and multiple api.php files but most of the routes defined in these files are Orion::resource .

about namespaces, yes i have a controllers namespace per module i create.

for example one of my api.php is like this:
`

  /**
   *
   * User Resources
   */
  Route::group(['prefix'=>'user'], function (){
      Orion::resource('/category', CategoryController::class);
      Orion::resource('/assigned/category', AssignedCategoryController::class);
      Orion::resource('/bank/info', BankInfoController::class);
      Orion::resource('/address', AddressController::class);
      Orion::resource('/company/profile', CompanyProfileController::class);
      Orion::resource('/profile', UserProfileController::class);
      Orion::resource('/favorite', FavoriteController::class);
      Orion::resource('/notify/me', NotifyMeController::class);
  });

  /**
   *
   * Content Resources
   */
  Route::group(['prefix'=>'content'],function (){
      Orion::resource('/custom/modal', CustomModalController::class);
      Orion::resource('/slider/item', SliderItemController::class);
      Orion::resource('/slider', SliderController::class);
      Orion::resource('/blog', BlogController::class);
      Orion::resource('/menu/item', MenuItemController::class);
      Orion::resource('/menu', MenuController::class);
      Orion::resource('/static/page', StaticPageController::class);
      Orion::resource('/block/item', BlockItemController::class);
      Orion::resource('/block', BlockController::class);
      Orion::resource('/seo', SeoController::class);
      Orion::resource('/tag/category', TagCategoryController::class);
      Orion::resource('/tag', TagController::class);
      Orion::resource('/comment', CommentController::class);
      Orion::resource('/meta/tag', MetaTagController::class);
      Orion::resource('/region', RegionController::class);
      Orion::resource('/entity/tag', EntityTagController::class);
      Orion::resource('/contact/us', ContactUsController::class);
  });


  /**
   *
   * Localization Resources
   */
  Route::group(['prefix' => 'localization'], function (){
      Orion::resource('/language', LanguageController::class);
      Orion::resource('/translation', TranslationCOntroller::class);
  });

  /**
   *
   * Marketplace Resource
   */
  Route::group(['prefix'=>'marketplace'], function (){
      Orion::resource('/user', UserMarketController::class);
      Orion::resource('/transaction', TransactionController::class);
      Orion::resource('/variation', \Modules\Admin\Http\Controllers\Marketplace\VariationController::class);
  });

  /**
   *
   * Sms Resources
   */
  Route::group(['prefix'=>'sms'], function (){
      Orion::resource('/setting', SmsSettingController::class);
      Orion::resource('/log', LogController::class);
  });


  /**
   *
   * Payment Resources
   */
  Route::group(['prefix'=>'payment'], function (){
      Orion::resource('/cart/to/cart', CartToCartController::class);
      Orion::resource('/status', \Modules\Admin\Http\Controllers\Payment\StatusController::class);
      Orion::resource('/type', TypeController::class);
      Orion::resource('/used/discount', UsedDiscountController::class);
      Orion::resource('/', PaymentController::class)->parameter('','payment');
  });


  /**
   *
   * Product Resource
   */
  Route::group(['prefix'=>'product'], function (){
      Orion::resource('/price/type/role', PriceTypeRoleController::class);
      Orion::resource('/price/type', PriceTypeController::class);
      Orion::resource('/currency', CurrencyController::class);
      Orion::resource('/guarantee/company', GuaranteeCompanyController::class);
      Orion::resource('/status', StatusController::class);
      Orion::resource('/brand', BrandController::class);
      Orion::resource('/discount', DiscountController::class);
      Orion::resource('/variation/file', VariationFileController::class);
      Orion::resource('/variation/price', VariationPriceController::class);
      Orion::resource('/variation/discount', VariationDiscountController::class);
      Orion::resource('/variation', VariationController::class);
      Orion::resource('/related', RelatedController::class);
      Orion::resource('/image', ImageController::class);
      Orion::resource('/special/offer', SpecialOfferController::class);
      Orion::resource('/user/discount', UserDiscountController::class);
      Orion::resource('/category', \Modules\Admin\Http\Controllers\Product\CategoryController::class);
      Orion::resource('/', ProductController::class)->parameter('','product');
  });


  /**
   *
   * Field Resources
   */
  Route::group(['prefix' => 'field'], function (){
      Orion::resource('/item/value', ItemValueController::class);
      Orion::resource('/entity/item/value', EntityItemValueController::class);
      Orion::resource('/item', ItemController::class);
      Orion::resource('/assigned/category', FieldAssignedCategoryController::class);
      Orion::resource('/', FieldController::class)->parameter('','field');
  });


  /**
   *
   * Order Resources
   */
  Route::group(['prefix'=>'order'],function (){
      Orion::resource('/status', \Modules\Admin\Http\Controllers\Order\StatusController::class);
      Orion::resource('/shipping/type', ShippingTypeController::class);
      Orion::resource('/shipping/setting', ShippingSettingController::class);
      Orion::resource('/shipment', ShipmentController::class);
      Orion::resource('/item', \Modules\Admin\Http\Controllers\Order\ItemController::class);
      Orion::resource('/', OrderController::class)->parameter('','field');
  });

  /**
   *
   * Bank gateway resource
   */
  Orion::resource('/bank/gateway', BankGatewayController::class);

  /**
   *
   * Site Setting Resource
   */
  Orion::resource('/site/setting', SiteSettingController::class);

`

[DenisJunio]

I had the same problem in my case it was due to the controllers namespace

@alireza2281 test with the following changes:

src/Specs/Builders/PathsBuilder.php in resolveRoute

    protected function resolveRoute(string $controller, string $operationName): Route
    {
        $prefix = '\\';
        if (strpos($controller, $prefix) === 0) {
            $controller = substr($controller, strlen($prefix));
        }

        return $this->router->getRoutes()->getByAction("{$controller}@{$operationName}");
    }

config/orion.php

return [
    'namespaces' => [
        'models'      => 'App\\Models\\',
        'controllers' => '', \\ <= Change here
    ],

[alexzarbn]

@alireza2281 @DenisJunio

I have created a dedicated issue for this, let's continue the discussion there.

Could you please let me know the Laravel version you are using?