README

简单易用的 OpenAPI 3 兼容文档生成器。
还包括 OpenAPI UI。

关于

1. OAS3 支持
2. 自动生成（假设已开启相关配置选项）
3. 包含 OpenAPI UI
4. 使用 PHP 8 属性

要求

此包是在 Laravel 8.19.0 上开发的，但可能在之前的版本中也能工作。
其他所有要求继承自 Laravel 8。
###此包需要 PHP 8 才能运行

安装

通过 composer 安装包

composer require freedomcore/laravel-openapi

发布配置文件和视图

php artisan vendor:publish --provider "FreedomCore\OpenAPI\OpenAPIServiceProvider"

编辑 openapi.php 配置文件以满足您的需求

包含内容

开箱即用，此包可以与 FormRequest 一起使用，它还能在参数包含在 query | path 中时生成有效的代码，因此不会有重复，并且 in: **** 也会正确分配。

使用方法

FreedomCore\OpenAPI\Attributes\Controller

控制器属性允许您将类标记为控制器。
这将帮助生成器识别类并为路由创建适当的标签。

/**
 * Class User
 * @package App\Http\Controllers\User
 */
#[FreedomCore\OpenAPI\Attributes\Controller(
    name: 'User',
    description: 'User related endpoints'
)]
class User extends Controller {

}

FreedomCore\OpenAPI\Attributes\Request\*

目前此包支持 5 种请求类型。

• FreedomCore\OpenAPI\Attributes\Request\Delete

/**
 * Delete constructor.
 * @param string $description
 * @param bool $deprecated
 */
public function __construct(string $description = '', bool $deprecated = false) {
    parent::__construct('DELETE', $description, $deprecated);
}

• FreedomCore\OpenAPI\Attributes\Request\Get

/**
 * Get constructor.
 * @param string $description
 * @param bool $deprecated
 */
public function __construct(string $description = '', bool $deprecated = false) {
    parent::__construct('GET', $description, $deprecated);
}

• FreedomCore\OpenAPI\Attributes\Request\Patch

/**
 * Patch constructor.
 * @param string $description
 * @param bool $deprecated
 */
public function __construct(string $description = '', bool $deprecated = false) {
    parent::__construct('PATCH', $description, $deprecated);
}

• FreedomCore\OpenAPI\Attributes\Request\Post

/**
 * Post constructor.
 * @param string $description
 * @param bool $deprecated
 */
public function __construct(string $description = '', bool $deprecated = false) {
    parent::__construct('POST', $description, $deprecated);
}

• FreedomCore\OpenAPI\Attributes\Request\Put

/**
 * Put constructor.
 * @param string $description
 * @param bool $deprecated
 */
public function __construct(string $description = '', bool $deprecated = false) {
    parent::__construct('PUT', $description, $deprecated);
}

除非您想为资源添加描述，否则不需要使用这些属性，可请求的类型将根据 Laravel 路由系统推断。

FreedomCore\OpenAPI\Attributes\Response\*

目前此包支持 18 种响应类型。
它们都附带正确的响应代码，所以您只需（或无需）添加描述。

这是基本类

<?php namespace FreedomCore\OpenAPI\Attributes\Response;

use Attribute;

/**
 * Class Response
 * @package FreedomCore\OpenAPI\Attributes\Response
 */
#[Attribute(Attribute::TARGET_METHOD)]
class Response {

    /**
     * Response code
     * @var int
     */
    public int $code;

    /**
     * Response description
     * @var string
     */
    public string $description;

    /**
     * Response constructor.
     * @param int $code
     * @param string $description
     */
    public function __construct(int $code, string $description) {
        $this->code = $code;
        $this->description = $description;
    }

}

这是 FreedomCore\OpenAPI\Attributes\Response\Ok 响应的示例

<?php namespace FreedomCore\OpenAPI\Attributes\Response;

use Attribute;

/**
 * Class Ok
 * @package FreedomCore\OpenAPI\Attributes\Response
 */
#[Attribute(Attribute::TARGET_METHOD)]
class Ok extends Response {

    /**
     * Ok constructor.
     * @param string $description
     */
    public function __construct(string $description = '') {
        parent::__construct(200, $description);
    }

}

示例 User.php 控制器

<?php namespace App\Http\Controllers\User;

use App\Http\Requests\User\{
    AuthenticateRequest,
    CreateRequest,
    EmailRequest,
    UsernameRequest
};
use App\Http\Resources\User\{
    DeviceCollection,
    TokenCollection,
    UserResource
};
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;
use FreedomCore\OpenAPI\Attributes;
use App\Http\Controllers\Controller;
use App\Contracts\Repositories\UserRepositoryContract;
use App\Contracts\Repositories\UserDeviceRepositoryContract;

/**
 * Class User
 * @package App\Http\Controllers\User
 */
#[Attributes\Controller(
    name: 'User',
    description: 'User related endpoints'
)]
class User extends Controller {

    /**
     * User repository instance
     * @var UserRepositoryContract
     */
    private UserRepositoryContract $userRepository;

    /**
     * User Device repository instance
     * @var UserDeviceRepositoryContract
     */
    private UserDeviceRepositoryContract $userDeviceRepository;

    /**
     * User constructor.
     * @param UserRepositoryContract $userRepository
     * @param UserDeviceRepositoryContract $userDeviceRepository
     */
    public function __construct(
        UserRepositoryContract $userRepository,
        UserDeviceRepositoryContract $userDeviceRepository
    ) {
        $this->userRepository = $userRepository;
        $this->userDeviceRepository = $userDeviceRepository;
    }

    /**
     * E-Mail exists
     * @param EmailRequest $request
     * @return JsonResponse
     */
    #[
        Attributes\Response\Ok(
            description: 'Successfully queried E-Mail existence'
        ),
        Attributes\Request\Get(
            description: 'Check whether specified E-Mail exists in the database'
        )
    ]
    public function existsEmail(EmailRequest $request): JsonResponse {
        return response()->success('Successfully queried E-Mail existence', [
            'exists'    =>  $this->userRepository->emailExists($request->get('email'))
        ]);
    }

    /**
     * Username exists
     * @param UsernameRequest $request
     * @return JsonResponse
     */
    #[
        Attributes\Response\Ok(
            description: 'Successfully queried Username existence'
        ),
        Attributes\Request\Get(
            description: 'Check whether specified Username exists in the database'
        )
    ]
    public function existsUsername(UsernameRequest $request): JsonResponse {
        return response()->success('Successfully queried Username existence', [
            'exists'    =>  $this->userRepository->usernameExists($request->get('username'))
        ]);
    }

    /**
     * Create new user
     * @param CreateRequest $request
     * @return JsonResponse
     */
    #[
        Attributes\Request\Post('Create new user account using provided data'),
        Attributes\Response\Ok('Successfully created new account'),
        Attributes\Response\Forbidden('Invalid security code provided'),
        Attributes\Response\InternalServerError('Failed to create account')
    ]
    public function create(CreateRequest $request): JsonResponse {
        return $this->userRepository->create($request);
    }

    /**
     * Authenticate
     * @param AuthenticateRequest $request
     * @return JsonResponse
     */
    #[
        Attributes\Request\Post('Authenticate user using provided credentials'),
        Attributes\Response\Ok('Successfully authenticated user using provided credentials'),
        Attributes\Response\Unauthorized('Invalid credentials provided'),
        Attributes\Response\InternalServerError('Failed to authenticate user due to internal server error')
    ]
    public function login(AuthenticateRequest $request): JsonResponse {
        return $this->userRepository->login($request, $this->userDeviceRepository);
    }

    /**
     * Log Out
     * @param Request $request
     * @return JsonResponse
     */
    #[
        Attributes\Request\Post('Log Out currently authenticated user'),
        Attributes\Response\Ok('Successfully logged out currently authenticated user'),
        Attributes\Response\InternalServerError('Failed to log out authenticated user due to internal server error')
    ]
    public function logout(Request $request): JsonResponse {
        return $this->userRepository->logout($request);
    }

    /**
     * Me
     * @param Request $request
     * @return UserResource
     */
    #[
        Attributes\Request\Get('Retrieve user information from request'),
        Attributes\Response\Ok('Successfully fetched information for currently authenticated user'),
        Attributes\Response\Forbidden('Invalid authorization token provided'),
        Attributes\Response\InternalServerError('Failed to fetch information for authenticated user due to internal server error')
    ]
    public function user(Request $request): UserResource {
        return new UserResource($this->userRepository->fromRequest($request));
    }

    /**
     * My Devices
     * @param Request $request
     * @return DeviceCollection
     */
    #[
        Attributes\Request\Get('Get list of devices associated with account'),
        Attributes\Response\Ok('Successfully fetched list of devices for currently authenticated user'),
        Attributes\Response\Forbidden('Invalid authorization token provided'),
        Attributes\Response\InternalServerError('Failed to fetch devices list for authenticated user due to internal server error')
    ]
    public function devices(Request $request): DeviceCollection {
        return new DeviceCollection($this->userDeviceRepository->forUser($request->user()));
    }

    /**
     * My Tokens
     * @param Request $request
     * @return TokenCollection
     */
    #[
        Attributes\Request\Get('Get list of tokens associated with account'),
        Attributes\Response\Ok('Successfully fetched list of tokens for currently authenticated user'),
        Attributes\Response\Forbidden('Invalid authorization token provided'),
        Attributes\Response\InternalServerError('Failed to fetch tokens list for authenticated user due to internal server error')
    ]
    public function tokens(Request $request): TokenCollection {
        return new TokenCollection($this->userRepository->tokens($request));
    }

}

以下是 WebUI 的外观：