README

此包包含文档生成器和文档查看器。打包的从文件夹中读取json并将其转换为包含API信息的网站。它还包括一个生成器。

安装

composer require "ilovelaravel/docs":"dev-master"

发布配置配置

php artisan vendor:publish

用法

所有需要的文件都存储在 storage/docs 中。主要文件是 storage/docs/api.json。

所有生成的文件都存储在 storage/docs/generated 中。生成后，将它们复制到 storage/docs 中。

您可以通过添加条目到您的 .env 文件来控制文档页面从哪里提供。

我在编写文档时使用以下设置：DOCS_DIRECTORY=storage/docs/generated ...当我满意时，我会将其改为：DOCS_DIRECTORY=storage/docs

生成器

运行以下命令以生成文件

php artisan api:docs:generate

您将找到以下结构

# Main file which structure we use to create the views
/api.json    

# Example request + response objects
/examples
/examples/<collection_name>/responses/named.route.json
/examples/<collection_name>/requests/named.route.json

# Examples of headers for the requests
/headers

# All the resources(GET,POST,PUT,DELETE) per collection 
/resources
/resources/<collection_name>.json

路由准备

路由应如下所示

$this->get('users', 'UsersController@index')->name('api.users.index')->middleware('can:users.read');

生成器仅查看以 api 开头的命名路由。例如：->name(api.something.something) 生成器可以从使用 can 中间件的路线中提取权限。

前端视图当前显示一个菜单，可以通过以下方式准备路线来构建

# group names turn in to menu items. Below 'general', will be the parent. 
# collection will be the name of the child menu name.
$this->group(['group'=>'general','collection'=>'users'],
    function() {
        // ..
    });
$this->group(['group'=>'general','collection'=>'dogs'],
    function() {
        // ..
    });        

$this->group(['group'=>'addresses','collection'=>'companies'],
    function() {
        // ..
    });

这将产生如下菜单

General
    - Users
    - Dogs
Addresses
    - Companies

控制器准备

应将注释放在控制器方法上。

@NoAuth 对于不需要 身份验证 的方法
@Title("显示所有用户") 描述API操作的标题
@Info("这将返回所有用户") 关于操作的一些信息

    /**
     * @Title("Show all users")
     * @Info("This will return all users")
     * @return JsonResponse
     */
    public function index(): JsonResponse
    {
        // ..
    }

表单请求准备

如果您为新的API操作创建新的表单请求，则可以使用 artisan 命令

docs:make:request AddUserRequest

如果您更新现有的表单请求对象，则应添加 Guarded 特性和实现 ApiRequestContract 协议。

rules() 和 schema 方法至少应返回一个空数组；

// Regular request validation rules. Please always fill this completely,  
// also for optional(nullable) fields

public function rules() 
{
   return [
       'first_name' => 'required|string'
   ]
}


// This will show up in the documentation. The format is:
// array('parameter key','validation rules','example of expected input') 

public function schema() 
{
   // Faker can be used to generated example output
   $faker = \Faker\Factory::create();
   
   return [
       ['first_name','required|string', $faker->firstName], // use faker like this
       ['key','validation','example'], // etc etc
       ['key','validation','example']  // etc
   ]
}

响应

文件夹 examples 的结构如下：

examples/
example/requests/named.route.namespace.json
example/responses/named.route.namespace.json

请求和响应文件与您的命名路由同名。所有生成的文件都将存储在 docs/generated 文件夹中。这应该是您的主要文件夹。在配置中配置此内容。将文件从那里复制到主文件夹。这样，您可以在不丢失已生成信息的情况下预览更改。

路由命令

php artisan docs:routes 将为您提供将要使用的路由的干净预览

视图

可以在浏览器中查看文档：http(s)://your-url.something/docs

如果您想编辑视图，则需要发布它们。发布视图后，模板视图位于：resources/views/docs

我很快且很棒地创建了此生成器。对我来说，最不重要的一部分是视图，因此它们包含了一些内联javascript和一些css的可爱拼凑，如果您有兴趣，可以进行重构。对我来说，这绝对不是优先事项。

变更日志

请参阅变更日志以获取有关最近更改的更多信息。

测试

您可以使用此命令来查看是否没有任何操作。可能存在一些错误。

composer test

鸣谢

Xander Smalbil

许可协议

MIT 许可协议（MIT）。请参阅许可文件以获取更多信息。

ilovelaravel/docs

维护者

详情