README

此包实现了2.1.1 json版本中强大的Postman JSON导出器。

包与amondar/rest-actions直接集成。

注意！！！请不要为此导出器使用非API路由，这将在导出过程中导致会话管理问题。

安装

要安装此包

将其添加到您的composer.json

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

认证您的composer以使用私有attractgroup仓库。

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

然后执行

composer require attract-cores/postman-documentation

之后，您可以使用artisan命令

php artisan export:postman

所有创建的JSON文档都将保存在项目内部/storage/app/public/postman/*目录中。

配置

授权类型和技巧

该包支持多种授权类型

oauth2
token
none

当使用none类型时，结果路由将创建空的auth块。此选项更适合具有自定义认证系统的旧项目。

当使用token类型时，结果路由将创建简单的Api Key授权选项。在这种情况下，最终用户在导入后应手动将api_key放入每个路由中。

当使用oauth2类型时，结果路由将创建OAuth 2.0授权选项。根据中间件设置auth_middleware或client_auth_middleware，将使用password或client_credentials授权类型。在某些项目中可以实现匿名授权。在这种情况下，您可以通过配置auth_type=oauth2运行命令并添加--personal-access选项。

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

在这种情况下，将为每个路由添加Bearer Token授权选项。此技巧可以用于旧项目，该项目使用了passport但没有开启token路由。只需像上面描述的那样运行命令，无需更改。

表单数据来自表单工厂

如果命令使用enable_formdata=true运行，则可以为每个请求类型（POST、PUT、PATCH、GET、DELETE）为每个路由指定表单工厂。默认情况下，所有工厂应放置在./app/Postman目录中。

每个工厂应按以下模式命名，并扩展核心工厂类，就像laravel中的标准模型工厂一样

${FULL_REQUEST_NAME}Factory.php

#For example

UserProfileRequestFactory.php

每次分发命令时，都会将所有工厂加载到内存中。

工厂类示例如下

<?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,
        ];
    }

}

每个工厂都初始化了$this->faker实例，就像laravel中的模型工厂一样。

如果您需要为每种REST标准请求类型创建专用表单，则可以添加例如public function postDefinition()函数，并添加与默认不同的definition()表单正文。

路由文档

该包添加了一些钩子方法和类，可以帮助您在Postman Markdown中生成路由的文档。您可以在不使用以下技巧的情况下导出Postman收藏集，但要为项目制作完整的文档，您需要更多解释和描述。

路由技巧

使用示例

<?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可以使用与简单Route相同的函数来设置资源上的设置和描述。

此示例将生成以下结构

文档将如下所示

Markdown

该包实现了MarkdownDocs类。该类可以轻松地使用美观的函数结构创建Markdown语法，就像laravel的Email类。

您可以使用->raw功能来插入另一个Markdown类实例的结果

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

devtools-marvellous / postman-documentation

维护者

详细信息