NAME

Kernel::WebApp::Controller::API::Role::HasEndpointDocumentation – Role for API endpoints that provides documentations.

PUBLIC INTERFACE

Expects methods to be defined in endpoints that are used to document the purpose of endpoints, their needed authentication, HTML response codes and data validation. Information about input data validity with the purpose of documentation, will be provided automatically, if the endpoint consumes the role Kernel::WebApp::Controller::API::Role::ValidatesInputData.

Description()

Method that holds the endpoint description / information about it's purpose. Endpoints can define it like this:

    sub Description {
        return 'List ticket data.';
    }

ExampleResponses()

Method that holds the information about HTML response codes. Endpoints can define it like this:

    sub ExampleResponses {
        return {
            200 => {
                Description => 'Returning a list of available ticket data.',
                Example     => {
                    List => [
                        {
                            TicketID     => 123,
                            TicketNumber => '20101027000001',
                            Title        => 'some title',
                            Preview      => 'Some ticket preview',
                            Attachments  => ['test'],
                            Created      => '2010-10-27 20:15:15',
                        },
                        {
                            TicketID     => 234,
                            TicketNumber => '20111027000002',
                            Title        => 'another title',
                            Preview      => 'Another ticket preview',
                            Attachments  => ['test', 'another_test' ],
                            Created      => '2011-10-27 22:22:22',
                        },
                    ],
                    Meta => {
                        Total          => 2,
                        Page           => 1,
                        TicketsPerPage => 2,
                    },
                },
            },
        };
    }

CollectEndpointDocumentation()

The "CollectEndpointDocumentation()" method collects the information provided by endpoints via the related methods of the roles:

Kernel::WebApp::Controller::API::Role::HasEndpointDocumentation Kernel::WebApp::Controller::API::Role::ValidatesInputData

The collected data will be summarized and provided as a hash reference:

    {
        SecuredBy   => 'CustomerAccessToken',
        Description => 'List ticket data.'
        Responses   => {
            200 => {
                Description => 'Returning a list of available ticket data.',
                Example     => {
                    List => [
                        {
                            TicketID     => 123,
                            TicketNumber => '20101027000001',
                            Title        => 'some title',
                            Preview      => 'Some ticket preview',
                            Attachments  => ['test'],
                            Created      => '2010-10-27 20:15:15',
                        },
                        {
                            TicketID     => 234,
                            TicketNumber => '20111027000002',
                            Title        => 'another title',
                            Preview      => 'Another ticket preview',
                            Attachments  => [ 'test', 'another_test' ],
                            Created      => '2011-10-27 22:22:22',
                        },
                    ],
                    Meta => {
                        Total          => 2,
                        Page           => 1,
                        TicketsPerPage => 2,
                    },
                },
            },
            422 => {
                Description => 'Invalid input data.',
                Example     => {
                    InvalidData => {
                        DataKey => 'WrongDataValue',
                    },
                },
            },
        },
        UriParameters => {
            TicketID => {
                Type     => t('PositiveInt'),
                Optional => 0,
                Example  => 123,
            },
        },
        QueryParameters => {
            TicketID => {
                Type     => t('PositiveInt'),
                Optional => 0,
                Example  => 123,
            },
        },
        JSONBodyFields => {
            TicketID => {
                Type     => t('PositiveInt'),
                Optional => 0,
                Example  => 123,
            },
        },
    }