service doges

servicedocs

OR

Not eye-gouging-ly ugly, usable interactive REST API documentation that stays up to date

service-docs.adeslade.co.uk

github.com/adeslade/interactive-service-description

Documentation generated from Guzzle service descriptions

What's Guzzle?

PHP HTTP Client

use Guzzle\Http\Client;

// Create a client and provide a base URL
$client = new Client('https://api.github.com');

$request = $client->get('/user');
$request->setAuth('user', 'pass');

// You must send the request
$response = $request->send();

echo $response->getBody();
// >>> {"type":"User", ...

What's a service description?

"Service descriptions define web service APIs by documenting each operation, the operation's parameters, validation options for each parameter, an operation's response, how the response is parsed, and any errors that can be raised for an operation."

    



{
    "operations": {
        "GetUsers": {
            "httpMethod": "GET",
            "uri": "/users",
            "summary": "Gets a list of users",
            "responseClass": "GetUsersOutput"
        }
     }
}

Using the "GetUsers" description in PHP

use Guzzle\Service\Description\ServiceDescription;

$description = ServiceDescription::factory(
    '/path/to/client.json'
);
$client->setDescription($description);

$command = $client->getCommand('GetUsers');
$responseModel = $client->execute($command);
echo $responseModel;

Service docs takes the service description and generates a bunch of HTML

It's demo time

service-docs.adeslade.co.uk

github.com/adeslade/interactive-service-description