API 文档 (已废弃,可手动集成)

  1. php bin/console doc

命令会将数据按照 app.php 配置的应用名进行生成,打开 html 文件即可访问文档。

文档的方式通过注释进行处理,定义在控制器中,更具体的操作请前往 swagger getting started

注释示例:

控制器
  1. <?php
  2. /**
  3. * @author jan huang <bboyjanhuang@gmail.com>
  4. * @copyright 2016
  5. *
  6. * @link https://www.github.com/janhuang
  7. * @link http://www.fast-d.cn/
  8. */
  9. namespace Http\Controller;
  10. use FastD\Http\JsonResponse;
  11. use FastD\Http\Response;
  12. use FastD\Http\ServerRequest;
  13. /**
  14. *
  15. * @SWG\Info(title="演示API", version="0.1")
  16. *
  17. * Class IndexController
  18. * @package Http\Controller
  19. */
  20. class IndexController
  21. {
  22. /**
  23. * @SWG\Get(
  24. * path="/foo/{name}",
  25. * summary="演示API示例",
  26. * tags={"demo"},
  27. * description="示例说明",
  28. * consumes={"application/json", "application/xml"},
  29. * produces={"application/json", "application/xml"},
  30. * @SWG\Parameter(
  31. * name="id",
  32. * in="query",
  33. * description="演示id",
  34. * required=false,
  35. * type="integer",
  36. * @SWG\Items(type="integer", format="int32"),
  37. * collectionFormat="csv"
  38. * ),
  39. * @SWG\Parameter(
  40. * name="status",
  41. * in="query",
  42. * description="演示status",
  43. * required=false,
  44. * type="integer",
  45. * enum={"available", "pending", "sold"}
  46. * ),
  47. * @SWG\Response(
  48. * response=200,
  49. * description="OK",
  50. * examples={
  51. * "application/json": {
  52. * "id"="1",
  53. * "status"="1"
  54. * }
  55. * },
  56. * @SWG\Schema(
  57. * type="integer"
  58. * ),
  59. * @SWG\Schema(
  60. * type="object",
  61. * @SWG\Property(property="error_code", type="integer", format="int32"),
  62. * @SWG\Property(property="error_message", type="string")
  63. * )
  64. * ),
  65. * @SWG\Response(response=400, description="Bad Request", @SWG\Schema(ref="#/definitions/User")),
  66. * @SWG\Response(response=500, description="Internal Server Error")
  67. * )
  68. *
  69. * @param $request
  70. * @return Response
  71. */
  72. public function welcome(ServerRequest $request)
  73. {
  74. return json([
  75. 'foo' => 'bar'
  76. ]);
  77. }
  78. /**
  79. * @param ServerRequest $request
  80. * @return JsonResponse
  81. */
  82. public function sayHello(ServerRequest $request)
  83. {
  84. return json([
  85. 'foo' => $request->getAttribute('name'),
  86. ]);
  87. }
  88. /**
  89. * @param ServerRequest $serverRequest
  90. * @return JsonResponse
  91. */
  92. public function middleware(ServerRequest $serverRequest)
  93. {
  94. return json([
  95. 'foo' => 'bar'
  96. ]);
  97. }
  98. /**
  99. * @return JsonResponse
  100. */
  101. public function db()
  102. {
  103. return json(
  104. database()->info()
  105. );
  106. }
  107. public function model()
  108. {
  109. $model = model('demo');
  110. return json([
  111. 'model' => get_class($model),
  112. 'db' => $model->getDatabase()->info()
  113. ]);
  114. }
  115. public function auth()
  116. {
  117. return json([
  118. 'foo' => 'bar'
  119. ]);
  120. }
  121. }

模型

  1. <?php
  2. /**
  3. * @author jan huang <bboyjanhuang@gmail.com>
  4. * @copyright 2016
  5. *
  6. * @link https://www.github.com/janhuang
  7. * @link http://www.fast-d.cn/
  8. */
  9. namespace Document;
  10. /**
  11. * @SWG\Definition(type="object", @SWG\Xml(name="User"))
  12. */
  13. class User
  14. {
  15. /**
  16. * @SWG\Property(format="int64")
  17. * @var int
  18. */
  19. public $id;
  20. /**
  21. * @SWG\Property()
  22. * @var string
  23. */
  24. public $username;
  25. /**
  26. * @SWG\Property
  27. * @var string
  28. */
  29. public $firstName;
  30. /**
  31. * @SWG\Property()
  32. * @var string
  33. */
  34. public $lastName;
  35. /**
  36. * @var string
  37. * @SWG\Property()
  38. */
  39. public $email;
  40. /**
  41. * @var string
  42. * @SWG\Property()
  43. */
  44. public $password;
  45. /**
  46. * @var string
  47. * @SWG\Property()
  48. */
  49. public $phone;
  50. /**
  51. * User Status
  52. * @var int
  53. * @SWG\Property(format="int32")
  54. */
  55. public $userStatus;
  56. }

值得注意的是,Schema 中的 ref 是需要映射到一个数据模型当中,而这个数据模型会推荐存放在 Document 目录中,写法参考以上代码。

效果:

[效果]

下一节: 应用配置