为你的 API 添加文档跟完成一个 API 同样重要。为了使文档写起来更容易，这个包允许你在 controllers 中注释你的 API 然后通过 Artisan 命令生成文档。

To generate documentation you can use the api:docs command. The command has two required arguments, the name of the documentation and the version to generate.

生成文档你可以使用 api:docs 命令。这个命令有两个必要的参数，文档的名字和生成的版本。

For usage details see the section.

更多使用详情见 Commands 章。

Controllers can generally be represented as a resource. Resources may contain a number of actions which are represented by HTTP verbs.

控制器一般代表一个资源。资源可以包含若干代表 HTTP 动词的方法。

To define a resource we can use the annotation.

定义一个资源，我们可以使用 @Resource 注释。

The first parameter given to the resource is its identifier or the name of the resource. We can also give a base URI to the resource.

资源的第一个参数是它的标识符或者是资源的名字。我们也可以给一个资源基本的 URI。

  1. /**
  2.  * @Resource("Users", uri="/users")
  3.  */
  4. class UserController extends Controller
  5. {
  7. }

You can also provide a description of your resource prior to the annotation.

我们也可以在注释的前面提供一段资源的注释。

  1. /**
  2.  * User resource representation.
  3.  *
  4.  * @Resource("Users", uri="/users")
  5.  */
  6. class UserController extends Controller
  7. {
  9. }

An action is represented by a routable method on your controller.

You can describe your action with the short and long descriptions of a PHPDoc.

你可以通过短的或长的 PHPDoc 描述你的方法。

  1. /**
  2.  * Show all users
  3.  *
  4.  * Get a JSON representation of all the registered users.
  5.  */
  6. public function index()
  7. {
  9. }

@Get, , @Put, , @Delete

Each action is represented by an HTTP verb. You must provide a URI as the first parameter to the annotation.

每个方法代表一个 HTTP 动词。你必须提供一个 URI 作为注释的第一个参数。

@Versions

An action may be available across multiple API versions. When generating documentation this annnotation is used to determine what actions will be included once generated.

一个方法可以通过不同版本的api访问。当生成文档的时候，这个注释用来确定一次生成包含哪些方法。

  1. /**
  2.  * Show all users
  3.  *
  4.  * Get a JSON representation of all the registered users.
  5.  *
  6.  * @Get("/")
  8. public function index()
  9. {
  11. }

@Request

An action should define a request that can be executed that will result in a successful or unsuccessful response.

一个方法需要定义一个请求，将导致一个成功或不成功的响应。

A request should contain a body. Depending on the type of request the body will vary. For POST requests you can use a string, however you will also need to set the content type.

一个请求需要包含一个body。根据请求的类型，body 会不同。对于 POST 请求你可以使用一个字符串，但是你依然需要设置 content type。

  1. /**
  2.  * Register user
  3.  *
  4.  * Register a new user with a `username` and `password`.
  5.  *
  6.  * @Post("/")
  7.  * @Versions({"v1"})
  8.  * @Request("username=foo&password=bar", contentType="application/x-www-form-urlencoded")
  9.  */
  10. public function store()
  11. {
  13. }

If you’re sending JSON you can use an annotation array and it will automatically be encoded to a JSON string. The content type will default to application/json.

如果你发送 JSON 数据，你可以使用数组进行注释，它将自动的编码为 JSON 字符串。content type 将默认为 application/json。

  1. /**
  2.  * Register user
  3.  *
  4.  * Register a new user with a `username` and `password`.
  5.  *
  6.  * @Post("/")
  7.  * @Versions({"v1"})
  8.  * @Request({"username": "foo", "password": "bar"})
  9.  */
  10. public function store()
  11. {
  13. }

You can also include additional headers.

你依然可以引入额外的头。

如果你的方法对不同的请求会有不同的响应，那么你必须标识请求。

  1. /**
  2.  * Register user
  3.  *
  4.  * Register a new user with a `username` and `password`.
  5.  *
  6.  * @Post("/")
  7.  * @Versions({"v1"})
  8.  * @Request({"username": "foo", "password": "bar"}, identifier="A")
  9.  */
  10. public function store()
  12. }

@Response

An should always be followed by an which defines the status code along with the content type, body, and headers.

一个 @Request 也需要定义一个 ，它定义了状态码，以及content type, body 和 headers。

Much like a request the response body can be a string (make sure to change the contentType) or an annotation array which will be encoded as JSON.

像请求一样，响应的 body 可以是一个字符串(确保要更改 contentType) 或者一个JSON 数组的注释。

  1. /**
  2.  * Register user
  3.  *
  4.  * Register a new user with a `username` and `password`.
  5.  *
  6.  * @Post("/")
  7.  * @Versions({"v1"})
  8.  * @Request({"username": "foo", "password": "bar"})
  9.  * @Response(200, body={"id": 10, "username": "foo"})
  10.  */
  11. public function store()
  12. {
  14. }

Like a request you can also include headers.

像请求一样，你依然可以引入头信息。

A transaction lets you define multiple requests and multiple responses for requests. Responses must follow requests however you can define multiple responses for a single request.

一个 transaction 允许你定义多个请求和多个响应。响应必须跟随请求，但你可以为一个请求定义多个响应。

  1. /**
  2.  * Register user
  3.  *
  4.  * Register a new user with a `username` and `password`.
  5.  *
  6.  * @Post("/")
  7.  * @Versions({"v1"})
  8.  * @Transaction({
  9.  *      @Request({"username": "foo", "password": "bar"}),
  10.  *      @Response(200, body={"id": 10, "username": "foo"}),
  11.  *      @Response(422, body={"error": {"username": {"Username is already taken."}}})
  12.  * })
  13.  */
  14. public function store()
  15. {
  17. }

If your URI contains query string parameters you can define them either at the resource level or the action level. If a parameter is defined at the resource level you will need to either define it for each action or on the resource.

如果你的 URI 包含查询参数，你可以在资源级别或者方法级别定义他们。如果一个参数定义在资源你级别，你需要为每个方法或资源定义它。

You can also define the parameters type and whether or not it’s required.

你也可以定义 type 参数，无论它是否 必要

  1. /**
  2.  * @Parameters({
  3.  *      @Parameter("example", type="integer", required=true, description="This is an example.", default=1)
  4.  * })
  5.  */
  6. public function index()
  7. {

← Making Requests To Your API |