NAME

Text::API::Blueprint - Markdown generator for API blueprint format

VERSION

version 0.003

FUNCTIONS

Compile

    Compile({
        # Meta
        host => 'hostname',
        # Intro
        name => 'title',
        description => 'short introduction',
        resources => [
            # Resource
            {
                ...
            }
        ],
        groups => [
            # Group
            name => [
                # Resource
                {
                    ...
                }
            ]
        ],
    });

Section

    Section(sub {
        ...
    })

Invokation: Section( CodeRef $coderef, [ Int $offset = 1 ])

Increments header offset by $offset for everything executed in $coderef.

Meta

    Meta();
    Meta('localhost');

Invokation: Meta([ Str $host ])

    FORMAT: 1A8
    HOST: $host

Intro

    Intro('Our API');
    Intro('Our API', 'With a short introduction');

Invokation: Intro(Str $name, [ Str $description ])

    # $name
    $description

Concat

    Concat('foo', 'bar');

Invokation: Concat( Str @blocks )

    $block[0]

    $block[1]

    $block[2]

    ...

Text

    Text('foo', 'bar');

Invokation: Text( Str @strings )

    $string[0]
    $string[1]
    $string[2]
    ...

Code

    Code('foobar');
    Code('{"foo":"bar"}', 'json');

Invokation: Code(Str $code, [ Str $lang = '' ])

    ```$lang
    $code
    ```

Group

    Group('header', 'body');
    Group('name', [
        # Resource
        {
            ...
        }
    ]);

Invokation: Group(Str $identifier, Str|ArrayRef[HashRef|Str] $body)

If $body is an ArrayRef, every item which is a HashRef will be passed to "Resource".

    # Group $identifier

    $body

Resource

    Resource({
        ...
    });

Invokation: Resource(HashRef $args)

Allowed keywords for $args:

• method, uri, identifier

  With method and uri

      ## $method $uri
  
      $body

  With identifier and $uri

      ## $identifier [$uri]
  
      $body

  With uri

      ## $uri
  
      $body

  Other combinations are invalid.

• body

  If body isa CodeRef, see "Section". description, parameters, attributes, model, actions are not allowed then.

• description

  A short introduction as a single string.

• parameters

  See "Parameters".

• attributes

  See "Attributes".

• model

  See "Model".

• actions

  Isa ArrayRef.

  See "Action".

Model

    Model({
        type => 'mime/type',
        # Payload
        ...
    });
    Model('mime/type', 'payload');

Invokation: Model(Str $media_type, Str|HashRef $payload, [ Int $indent ]);

See "Payload" if the first and only argument is a HashRef.

    + Model ($media_type)

    $payload

Schema

    Schema('body');

Invokation: Schema(Str $body, [ Int $indent ])

    + Schema

    $body

Attribute

    Attribute('scalar', {
        type => 'string',
        example => 'foobar',
        description => 'a text',
    });
    Attribute('list', {
        enum => 'number',
        example => 3,
        description => 'a number from 1 to 5',
        members => [1,2,3,4,5],
    });
    Attribute('hash' => [
        foo => {
            type => 'string',
            ...
        },
        bar => {
            ...
        }
    ]);

Attributes

    Attributes('reference');
    Attributes([
        # Attribute
        name => {
            ...
        }
    ]);

Action

    Action({
        ...
    });

Invokation: Action(HashRef $args)

Allowed keywords for $args:

• identifier, method, uri

  With $identifier $method and $uri:

      ### $identifier [$method $uri]
  
      $body

  With $identifier and $method:

      ### $identifier [$method]
  
      $body

  With $method:

      ### $method
  
      $body

  Other combinations are invalid.

• description

• relation

  See "Relation".

• parameters

  See "Parameters".

• attributes

  See "Attributes".

• assets

  Isa ArrayRef interpreted as a key/value paired associative list.

  The key is splited into two parts by the first whitespace, named keyword and id.

  If the value isa string, "Reference" is called with <<(keyword, id, value)>>

  If the value is anything else, "Asset" is called with <<(keyword, id, value)>>

• requests

  See "Request_Ref" if the value isa string. See "Request" otherwise.

• responses

  See "Response_Ref" if the value isa string. See "Response" otherwise.

Payload

    Payload({
        ...
    });

Invokation: Payload(HashRef $args)

Allowed keywords for $args:

• description

  A short introduction as a single string.

• headers

  See "Headers".

• attributes

  See "Attributes".

• body

  See "Body".

• code, lang

  See "Bode_CODE".

• yaml

  See "Body_YAML".

• json

  See "Body_JSON".

• schema

  See "Schema".

Asset

    Asset('Request', 'foo', {
        type => 'mime/type',
        # Payload
        ...
    });

Invokation: Asset( Str $keyword, Str $identifier, HashRef $payload )

See "Payload" for %payload

    # $keyword $identifier ($type)

    $payload

Reference

    Reference('Request', 'foo', 'bar');
    Reference('Response', 'foo', 'bar');

Invokation: Reference(Str $keyword, Str $identifier, Str $reference)

    # $keyword $identifier

        [$reference][]

Request

    Request('foo', { ... });

Invokation: Request(@args)

Calls "Asset"( 'Request', @args )

Request_Ref

    Request_Ref('foo', 'bar');

Invokation: Request_Ref(@args)

Calls "Reference"( 'Request', @args )

Response

    Response('foo', { ... });

Invokation: Response( @args )

Calls "Asset"( 'Response', @args )

Response_Ref

    Response_Ref('foo', 'bar');

Invokation: Response_Ref(@args)

Calls "Reference"( 'Response', @args )

Parameters

    Parameters([
        foo => {
            # Parameter
            ...
        },
        bar => {
            # Parameter
            ...
        }
    ]);

Invokation: Parameters(ArrayRef[Str|HashRef] $parameters)

For every keypair in @$parameters "Parameter"($key, $value) will be called

Parameter

    Parameter('foo', {
        example => 'foobar',
        required => 1,
        type => 'string',
        shortdesc => 'a string',
        longdesc => 'this is a string',
        default => 'none',
    });
    Parameter('foo', {
        example => '3',
        required => 0,
        enum => 'number',
        shortdesc => 'an optional number',
        longdesc => 'an integer between 1 and 5 (both inclusive)',
        default => 1,
        members => [1,2,3,4,5],
    });

Invokation: Parameter( Str $name, HashRef $args )

    + $name: `$example` ($type, $required_or_optional) - $shortdesc

        $longdesc

        + Default: `$default`

        + Members
            + `$key` - $value
            + ...

Headers

    Headers([
        FooBar => '...', # Foo-Bar
        -foof  => '...', # X-Foof
    ]);

Invokation: Headers(ArrayRef[Str] $headers)

The headers are encoded and prettified in a fancy way. See HTTP::Headers::Fancy for more information.

Body

    Body('foobar');

Invokation: Body( Str $body )

    + Body

            $body

Body_CODE

    Body_CODE('foobar');
    Body_CODE('foo', 'bar');

Invokation: Body_CODE( Str $code, Str $lang )

    + Body

        ```$lang
        $code
        ```

Body_YAML

    Body_YAML({ ... });
    Body_YAML([ ... ]);

Invokation: Body_YAML( HashRef|ArrayRef $struct )

    + Body

        ```yaml
        $struct
        ```

Body_JSON

    Body_JSON({ ... });
    Body_JSON([ ... ]);

Invokation: Body_JSON( HashRef|ArrayRef $struct )

    + Body

        ```json
        $struct
        ```

Relation

    Relation('foo');

Invokation: Relation( Str $link )

    + Relation: $link

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/zurborg/libtext-api-blueprint-perl/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

David Zurborg <zurborg@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2015 by David Zurborg.

This is free software, licensed under:

  The ISC License

cpanm Text::API::Blueprint

perl -MCPAN -e shell
install Text::API::Blueprint