pauldevelop/library-raml

Generate RAML documents from annotated class files.

library-raml

Generate RAML documents from annotated php source files., _(*1)

RAML is a modeling language for describing RESTful APIs and is a supplementary document that comes alongside with the API. To avoid a drifting apart of the implementation and it's documentation over time this library provides the ability to generate RAML documents based on the annotated source code files implementing the API., _(*2)

This does not solve the problem completely, because the annotations need to be kept up to date as well. In return they are "nearer" coupled with the code and located in the same file, which hopefully makes it more likely for them to get updated at all., _(*3)

Usage

The process of generating RAML documents consists of two processes: First, the parsing of source code files and looking for suitable annotations in file- and method-level docblocks. Secondly, the creation of a new RAML document based on the data the parser found in the source code files., _(*4)

Parsing

To find relevant RAML annotations in source files, use the Parser class to have them parsed., _(*5)

$annotations = Parser::process(
    '/path/to/class.php'
);

The process method returns a FileAnnotations object, which returns the annotations in docblocks on file-, class-, member-, method- and property-level., _(*6)

Supported annotations on file-level are:, _(*7)

• Title, _(*8)

  The title of the REST API. The title annotation is also used to merge related source files, which is necessary if the code which implements the API is organized in multiple files., _(*9)

• Version, _(*10)

  The version of the REST API., _(*11)

• BaseUri, _(*12)

  The base URI, where all resource request are based on. May contain variable parts like they are documented in the RAML specification, e. g. "https://api.example.com/{version}"., _(*13)

• MediaType, _(*14)

  The media type, the response is encoded, e. g. "application/json"., _(*15)

• Protocol, _(*16)

  The protocol that is used to access the API, e. g "HTTPS". If more than one protocol is supported, add as many protocol annotation tags as needed., _(*17)

• SecurityScheme, _(*18)

  Describing the supported security schemes. If more than one security scheme is supported, add as many annotation tags as needed. Example for basic authentication: name="basic", type="Basic Authentication"., _(*19)

An example of a file-level docblock containing RAML specific annotations:, _(*20)

/**
 * @\raml\annotations\Title(title="Karmap Core API")
 * @\raml\annotations\Version(version="v1")
 * @\raml\annotations\BaseUri(baseUri="https://api.core.karmap.com/{version}")
 * @\raml\annotations\MediaType(mediaType="application/json")
 * @\raml\annotations\Protocol(protocol="HTTPS")
 * @\raml\annotations\SecurityScheme(name="basic", type="Basic Authentication")
 */

/**
 * Class-level docblock
 */
class AClass {
   ...
}

After specifying general information about the REST API we now proceed to describing the operations the API consists of. In most cases a REST API call will be mapped to a class function, a method. Therefor methods need to be annotated by the following tags supported on method-level:, _(*21)

• Resource, _(*22)

  Specifies the part of the URI after the base URI, that is used to name a resource, e. g. "/albums"., _(*23)

• HttpVerb, _(*24)

  A HTTP verb, that is used to access a resource, e. g. "POST"., _(*25)

• Description, _(*26)

  Description of the resource or operation., _(*27)

• SecuredBy, _(*28)

  Use the name of one of the security schemes here, that were defined in a security scheme tag on file level, e. g. "basic"., _(*29)

• Parameter, _(*30)

  Use multiple parameter annotation tags to specify all parameters, that are necessary for an operation on the REST API. See the following source code snippet for an example., _(*31)

...
class AClass {
    ....

    /**
     * @\raml\annotations\Resource(resource="/anonymousInterpretations")
     * @\raml\annotations\HttpVerb(verb="POST")
     * @\raml\annotations\Description(description="Create anonymous interpretation")
     * @\raml\annotations\SecuredBy(scheme="basic")
     * @\raml\annotations\Parameter(
     *   parameterType="form",
     *   name="clientCode",
     *   displayName="Client code",
     *   description="Code identifying the client",
     *   type="string",
     *   pattern="^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
     *   required="true",
     *   example="b4762505-b108-46a0-a4c7-f79c4b224b58"
     * )
     */
    public function doSomething(...) {
    }

    ...
}

Generating

To generate a RAML document, use the Generator class., _(*32)