README

This package implements powerful postman json exporter in 2.1.1 json version.

Package integrated with amondar/rest-actions right of the box.

NOTE!!! Please, don't use this exporter for none API routes, that will cause problems with session management during exporting.

Installation

To install this package:

Add to your composer.json:

{
  "repositories": [
      {"type": "composer", "url": "https://repo.packagist.com/attractgroup/"}
  ]
}

Authenticate your composer to work with private attractgroup repo.

composer config --global --auth http-basic.repo.packagist.com ${USER} ${AUTH_TOKEN}

Then execute:

composer require attract-cores/postman-documentation

After that you can run artisan command:

php artisan export:postman

All created json docs will be saved at /storage/app/public/postman/* directory inside your project.

Configuration

Authorization types and tricks

Package support several authentication types:

oauth2
token
none

When none type used, result routes will be created with empty auth blocks. That option preferable on old projects with custom authentication system.

When token type used, result routes will be created with simple Api Key authorization option. In that case, end user, after import should place api_key into each route manually.

When oauth2 type used, result routes will be created with OAuth 2.0 authorization option. Depends on middleware settings auth_middleware or client_auth_middleware will be user password or client_credentials grant types. On some projects can be implemented anonymous authorization. In at case you can run command with configured auth_type=oauth2 and add --personal-access option.

php artinsan export:postman --personal-access={{user_access_token}}

In that case will be added Bearer Token authorization option to each route. That trick can be used on old projects, that used passport, but doesn't have opened token route. Just run command as described above without changing.

Form data from form factories

If command ran with enable_formdata=true then you can specify form factory for each route for each request type: POST, PUT, PATCH, GET, DELETE. By default, all factories should be placed in ./app/Postman directory.

Each factory should be named by a pattern below and extends core factory class, just like a standard model factories in laravel:

${FULL_REQUEST_NAME}Factory.php

#For example

UserProfileRequestFactory.php

All factories loaded into memory each time, when command dispatched.

Example of factory class looks like below:

<?php

namespace App\Postman;

use AttractCores\LaravelCoreKit\Http\Requests\UserProfileRequest;
use AttractCores\PostmanDocumentation\Factory\FormRequestFactory;
use Database\Factories\UserFactory;

/**
 * Class UserProfileRequestFactory
 *
 * @package App\Postman
 * Date: 01.12.2021
 * Version: 1.0
 */
class UserProfileRequestFactory extends FormRequestFactory
{

    /**
     * The name of the factory's corresponding form request.
     * @note Value of the $request property can be request class name or route name, 
     * so you can generate name of the factory as you want. 
     * Example - api.v1.profile.update
     * Example - UserProfileRequest::class
     *
     * @var string|null
     */
    protected ?string $request = UserProfileRequest::class;


    /**
     * Define the model's default state.
     *
     * @return array
     */
    public function definition() : array
    {
        return [
            'email'                 => $this->faker->email,
            'password'              => UserFactory::DEFAULT_PASSWORD,
            'password_confirmation' => UserFactory::DEFAULT_PASSWORD,
            'firebase_token'        => NULL,
            'name'                  => $this->faker->name,
        ];
    }

}

Each factory has initialized $this->faker instance, just like model factory in laravel.

If you need dedicated form for each type of REST standard request, then you can add, for example, public function postDefinition() function and add different from default definition() form body.

Route documentation

Package add several hook methods and classed that can help you generate docs for your routes right in Postman Markdown. You can export postman collection without any of below tricks, but to make full documentation for your project you need a little more explanations and descriptions.

Route tricks

Example of usage:

<?php
use AttractCores\PostmanDocumentation\PostmanAction;

Route::put('profile/referrals-settings', 'Api\ReferralsSettingsController@update')
     ->name('profile.referrals-settings.update')
     ->aliasedName('Update referrals settings')
     ->structureDepth(3)
     ->expands(App\Models\User::class, [
         'roles'   => [
             '*Roles expand for the user*',
             '*First Example* - `?expand=roles`',
         ],
         'zipCode' => 'Zip code expand. Each time requested on referral return distance from current user zip.',
     ])
     ->scopes(App\Models\User::class)
     ->description(
         \AttractCores\PostmanDocumentation\Facade\Markdown::heading('Here the new heading')
                                                           ->line('Some explanation line')
     );

// OR via resource

Route::apiResource('users', 'UserController')
      ->postman([
          'index'   => PostmanAction::fresh()
                                    ->aliasedName('Get list of users')
                                    ->expands(CoreUserContract::class),
          'show'    => PostmanAction::fresh()
                                    ->aliasedName('Get one user resource')
                                    ->expands(CoreUserContract::class),
          'store'    => PostmanAction::fresh()
                                    ->aliasedName('Create new user'),
          'update'     => PostmanAction::fresh()
                                    ->aliasedName('Update existing user'),
          'destroy' => PostmanAction::fresh()
                                    ->aliasedName('Delete existing user'),
      ]);

PostmanAction can use same functions as on simple Route to set settings and descriptions on resources.

This example will generate structure as described below:

Documentation will look like:

Markdown

Package implements MarkdownDocs class. That class can easily create markdown syntax with pretty functions structure, like laravel Email class.

You can use ->raw functionality to insert result of another markdown class instance:

Markdown::raw(Markdown::new()->line('Some another configured line'));

yurenery / postman-documentation

Maintainers

Details