README

自动为您的Laravel Dingo/API应用程序生成API文档。

安装

使用Composer安装该包

$ composer require johannesschobel/dingodocs

然后使用以下命令发布config文件

php artisan vendor:publish --provider="JohannesSchobel\DingoDocs\DingoDocsServiceProvider" --tag="config"

如果您想自定义API文档文件的输出，您可能还需要发布resource文件

php artisan vendor:publish --provider="JohannesSchobel\DingoDocs\DingoDocsServiceProvider" --tag="resources"

入门

该包旨在让开发者能够自动生成API文档文件，而不需要过多的负担。例如，该包试图从注释或要调用的方法参数中读取所需信息。

可用注释

目前，该包为以下注释提供功能

名称

为您的API端点提供的名称。

描述

对您的API端点的描述（长文本）。

HTTP方法

调用端点所需的相应HTTP方法（GET、POST、...）。

身份验证

如果您需要身份验证才能调用端点。

分组

将端点分组在一起的名字（例如，在生成的文件左侧导航栏中使用）。

角色

请求者调用端点所需具有的角色。

异常

端点可能抛出的异常，包括HTTP状态和进一步描述。

请求

调用端点的示例请求。

响应

从端点返回的示例响应。

转换器

由端点提供的转换器（及其包含项）。

瞬态

表示此端点是否列在生成的API文档中。

命令

简单调用

php artisan dingodocs:generate

以生成API文档。生成的文件随后存储在您应用程序的public文件夹中。

示例

以下示例说明了如何使用此包

// namespace and lots of use statements here

/**
 * Class FaqController
 * @package App\Http\Controllers
 *
 * @Group("Faqs")
 * @Authentication
 * @Role("Group")
 */
class FaqController extends ApiBaseController
{
    /**
     * Get all Faqs
     *
     * Returns all Faqs.
     *
     * @param Request $request
     * @return Response the result
     *
     * @Authentication("false")
     * @Transformer("\App\Transformers\FaqTransformer")
     */
    public function index(Request $request) {
        $faqs = Faq::all();

        return $this->response->collection($faqs, new FaqTransformer());
    }

    /**
     * Get one Faq
     *
     * Returns one Faq entry.
     *
     * @param Faq $faq to be displayed
     * @return Response the result
     *
     * @Transformer("\App\Transformers\FaqTransformer")
     * @Exceptions({
     *    @Exception("403", description="If the user is not logged in."),
     *    @Exception("400", description="If some other things happen."),
     * })
     */
    public function show(Faq $faq) {
        $user = authenticate(); // imagine, that this method will return a USER object or null!
        if(is_null($user)) {
            // do a fancy exception handling here!
        }
        
        // do another exception handling here.. 
        
        return $this->response->item($faq, new FaqTransformer());
    }
    
    /**
     * Store a new Faq
     * 
     * Add a new Faq entry to the database.
     * 
     * @param Request $request the request to be stored to the database
     * @return Response the result
     */
    public function store(FaqRequest $request) {
        $faq = new Faq();
        $faq->name = $request->input('name');
        $faq->save();

        return $this->response->created();
    }
}

如我们所见，一些注释可以放置在Class级别，而其他注释可以放置在Method级别。然而，方法注释会覆盖类注释（例如示例中的@Authentication注释）。

请注意，该包将尝试从store方法中解析出FaqRequest参数。此外，所有验证规则（例如，name => required|string|max:255）都会被解析并自动添加到文档中。