NelmioApiDocBundle

NelmioApiDocBundle是一個開源的Symfony組建，能夠自動生成每個bundle以及內部每個action的document，並支援sandbox測試，可以手動變數輸入，非常方便api的開發。

如何安裝

把下面的程式碼新增到composer.json檔案中

{
    "require": {
        "nelmio/api-doc-bundle": "dev-master"
    }
}

在核心檔案中app/AppKernel.php新增相應的bundle資訊

// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
    );
}
 

修改路由配置檔案routing.yml，新增路徑，以後就可以通過api/doc直接訪問

# app/config/routing.yml
NelmioApiDocBundle:
    resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
    prefix:   /api/doc

修改配置檔案app/config/config.yml，使其生效:

# app/config/config.yml
nelmio_api_doc: ~

具體在程式碼中如何新增

我們平時做開發最頭疼的一個問題就是如何使得文件能夠跟開發保持同步，如果修改文件也像修改程式碼那樣頻繁，一定需要花費大量的時間和精力去維護。這就是為什麼我推薦NelmioApiDocBundle

所有的API介面都寫在程式碼的annotation中，非常方便。

(由此可見，我們的程式碼的註釋也不一定是完全沒有用的，這一點在其他語言裡體現的也比較多，比如java。)

ApiDoc() 註釋

這個bundle為你的每個controller提供了ApiDoc()annotation

1. <?php
2. namespaceYour\Namespace;
3. useNelmio\ApiDocBundle\Annotation\ApiDoc;
4. classYourControllerextendsController
5. {
6. /**
7. * This the documentation description of your method, it will appear
8. * on a specific pane. It will read all the text until the first
9. * annotation.
10. *
11. * @ApiDoc(
12. * resource=true,
13. * description="This is a description of your API method",
14. * filters={
15. * {"name"="a-filter", "dataType"="integer"},
16. * {"name"="another-filter", "dataType"="string", "pattern"="(foo|bar) ASC|DESC"}
17. * }
18. * )
19. */
20. publicfunction getAction()
21. {
22. }
23. /**
24. * @ApiDoc(
25. * description="Create a new Object",
26. * input="Your\Namespace\Form\Type\YourType",
27. * output="Your\Namespace\Class"
28. * )
29. */
30. publicfunction postAction()
31. {
32. }
33. }
34. ?>

在註釋部分，有以下幾個屬性我們可以使用:

• section: 允許給資源分組

• resource: 是否這個函式描述了一個主要資源，預設是否

• description: 用來描述當前的函式

• deprecated: 允許把當前函式設定成deprecated，預設是否

• filters: 一個過濾陣列

• input: the input type associated to the method (currently this supports Form Types, classes with JMS Serializer metadata, and classes with Validation component metadata) useful for POST|PUT methods, either as FQCN or as form type (if it is registered in the form factory in the container).

• output: the output type associated with the response. Specified and parsed the same way as input.

• statusCodes: 狀態碼，如404，500等。比如下面的程式碼，

1. <?php
2. classYourController
3. {
4. /**
5. * @ApiDoc(
6. * statusCodes={
7. * 200="Returned when successful",
8. * 403="Returned when the user is not authorized to say hello",
9. * 404={
10. * "Returned when the user is not found",
11. * "Returned when somehting else is not found"
12. * }
13. * }
14. * )
15. */
16. publicfunction myFunction()
17. {
18. // ...
19. }
20. }

這個bundle也可以通過定義的路由來獲取資訊，比如requirements, pattern, 等等，所以為了最好地使用這個bundle，你應該嚴格定義每個函式的requirements等資訊。