austinvernsonger / services_documentation Goto Github PK

Project Description
================================================================================

Overview
--------------------------------------------------------------------------------
The Services Documentation module generates API documentation for your site's
Services resources. Most of the documentation is generated automatically, using
the resource information contained provided by Services. However, this module
provides you with the ability to easily extend that documentation.

We make the following assumptions about your usage of the Services module:

* You are providing an API to a third party, which allows them to access your
  data via Services.
* Your API will be organized by version. E.g., API version 1.x, 2.x, etc.
* You would like to provide a page to API consumers that documents your API
  endpoints, resources, etc.
* You have enough familiarity with Drupal to create a module and implement a
  hook.

Documentation will be made available on your Drupal site at /developers. It will
be organized by API version (arbitrarily defined by you), and subsequently
displayed hierarchically according to resource, method type, method name,
arguments, etc.

Usage
--------------------------------------------------------------------------------
A full example implementation can be found in
services_documentation/services_documentation.api.php

* Create a new, custom module. Let's call it myapi.module.
* Implement hook_services_resources_alter($resources);
* For each resource method that you would like to document, add two new rows to
  the $resource array: ‘documentation callback' and 'documentation versions'.
  <pre>
    $resources['user']['index']['documentation callback'] = '_myapi_index_doc';
    $resources['user']['index']['documentation versions'] = array(1000);
  </pre>
* Define the documentation callback, which should return an element in the
  following format:
  <pre>
  /**
   * Documentation callback for index operation of users resource.
   */
  function _myapi_uses_index_doc() {
    $element = array(
      '#name' => t('name'),
      '#description' => t('desc'),
      // Example request. E.g., a request URL, headers, and a JSON array.
      '#request' => t('request'),
      // Example response. E.g., a JSON array.
      '#response' => t('response'),
    );

    return $element;
  }
  </pre>

After enabling this module, a list of API version numbers will appear at
/developers. Clicking on the version number will display a list of resources,
their arguments, endpoints, etc.

Contributing
--------------------------------------------------------------------------------
Anyone is encouraged to contribute to this project.

By contributing to this project, you grant a world-wide, royalty-free,
perpetual, irrevocable, non-exclusive, transferable license to all users under
the terms of the Gnu General Public License v2 or later.

All comments, messages, pull requests, and other submissions received through
official White House pages including this Drupal.org page are subject to the
Presidential Records Act and may be archived. Learn more at
http://whitehouse.gov/privacy.

License
--------------------------------------------------------------------------------
This project constitutes a work of the United States Government and is not
subject to domestic copyright protection under 17 USC § 105.

The project utilizes code licensed under the terms of the GNU General Public
License and therefore is licensed under GPL v2 or later.

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program. If not, see http://www.gnu.org/licenses/.