-
Notifications
You must be signed in to change notification settings - Fork 2
Documenting your API
Resources are a collection of actions (endpoints). These can generally be referred to as a "controller" in a standard MVC application structure.
As long as a resource contains resource actions, there is nothing you need to do to document a resource. Resource action documentation will handle everything automatically.
A resource action (endpoint) is something that you can execute from your API.
Mill is currently a bit opinionated in how it expects the names of your action methods to be; it looks for methods in resources that have RESTful names: GET, POST, PUT, PATCH, and DELETE
Documenting a resource action is easy, however:
class UsersController extends \MyApplication\Controller
{
/**
* Search for users.
*
* @api-label Search
* @api-operationid searchUsers
* @api-group Users
*
* @api-path:public /users
*
* @api-contenttype application/json
*
* @api-queryparam:public page (integer) - The page number to show.
* @api-queryparam:public per_page (integer) - Number of items to show on
* each page. Max 100.
* @api-queryparam:public query (string, required) - Search query.
*
* @api-return:public collection (\MyApplication\Representation\User)
*
* @api-error:public 503 (\MyApplication\Representation\Error) - If search
* is disabled.
*/
public function GET()
{
...
}
}
Here we're denoting that the action:
- Powers "Search for users", by way of the non-annotated description
- Handles the
GET /users
- Returns its content as
application/json
- Has five three request parameters
- Returns a collection of User representations
- Can throw a
503 Service Unavailable
error if search is disabled.
A representation is an object of data that can be returned in a resource action. Since these cover a lot more data than a standard resource action, documenting them is a bit more work.
<?php
namespace \MyApplication\Representation
/**
* @api-label User
*/
class User extends \MyApplication\Representation
{
public function _json($user)
{
return [
/**
* @api-data uri (uri) - The canonical relative URI for the user.
*/
'uri' => sprintf('/users/%d', $user->id),
/**
* @api-data name (string) - The users' display name.
*/
'name' => $user->getName(),
/**
* @api-data metadata (object) - The users' metadata.
*/
'metadata' => [
/**
* @api-data metadata.connections (object) - A list of resource
* URIs related to the user.
*/
'connections' => [
/**
* @api-data metadata.connections.albums (object) - Info
* about the albums created by this user.
*/
'albums' => [
/**
* @api-data uri (uri) - URI that resolves to the
* connection data.
*/
'uri' => sprintf('/users/%s/albums', $user->id),
/**
* @api-data options (array) - Array of HTTP methods
* allowed on this URI.
*/
'options' => ['GET'],
/**
* @api-data total (number) - Total number of items on
* this connection.
*/
'total' => $user->getAlbums()->total
]
]
]
];
}
}
Here you can see that a User representation can contain:
uri
name
metadata[connections][albums]