RetailCRM-Mirror/NelmioApiDocBundle
1
0
Fork 0
mirror of https://github.com/retailcrm/NelmioApiDocBundle.git synced 2025-04-08 11:42:07 +00:00
Code Issues Projects Releases Wiki Activity
Generates documentation for your REST API from annotations
585 commits 9 branches 28 tags 17 MiB
Find a file
Bez Hermoso 14d1021c8b Unified data types [actualType and subType] 
This is the result of https://github.com/nelmio/NelmioApiDocBundle/issues/410.

This PR aims to provide a uniform way of declaring data-types of parameters for
parsers and handlers to follow. In turn, this would allow formatters to
determine data-types in a cleaner and less volatile manner. (See use-case that
can be improved with this PR:
https://github.com/nelmio/NelmioApiDocBundle/blob/master/Formatter/AbstractFormatter.php#L103)

This is possible by the addition two properties to each property item in
`response`, and `parameters` fields in each API endpoint produced by the
`ApiDocExtractor`:

* `actualType` Contains a value from one of the `DataTypes` class constants.

* `subType` Can contain either `null`, or any other `DataTypes` class constant.
This is relevant when the `actualType` is a `DataTypes::COLLECTION`, wherein
`subType` would specify the type of the collection items. It is also relevant
when `actualType` is a `DataTypes::MODEL`, wherein `subType` would contain an
identifier of the model (the FQCN or anything the parser would wish to specify)

Examples:

```php

array(
    'id' => array(
        'dataType' => 'integer',
        'actualType' => DataTypes::INTEGER,
        'subType' => null,
    ),
    'profile' => array(
        'dataType' => 'object (Profile)',
        'actualType' => DataTypes::MODEL,
        'subType' => 'Foo\Entity\Profile',
        'children' => array(
            'name' => array(
                'dataType' => 'string',
                'actualType' => DataTypes::STRING,
                'subType' => null,
             ),
            'birthDate' => array(
                'dataType' => 'date',
                'actualType' => DataTypes::DATE,
                'subType' => null,
            ),
        )
    ),
    'languages' => array(
        'dataType' => 'array of strings',
        'actualType' => DataTypes::COLLECTION,
        'subType' => DataTypes::STRING,
    ),
    'roles' => array(
        'dataType' => 'array of choices',
        'actualType' => DataTypes::COLLECTION,
        'subType' => DataTypes::ENUM,
    ),
    'groups' => array(
        'dataType' => 'array of objects (Group)',
        'actualType' => DataTypes::COLLECTION,
        'subType' => 'Foo\Entity\Group',
    ),
    'profileRevisions' => array(
         'dataType' => 'array of objects (Profile)',
         'actualType' => DataTypes::COLLECTION,
         'subType' => 'Foo\Entity\Profile',
    ),
    'address' => array(
        'dataType' => 'object (a_type_a_custom_JMS_serializer_handler_handles)',
        'actualType' => DataTypes::MODEL,
        'subType' => 'a_type_a_custom_JMS_serializer_handler_handles',
    ),
);
```

When a formatter omits the `dataType` property or leaves it blank, it is
inferred within `ApiDocExtractor` before everything is passed to formatters.
2014-06-25 09:05:48 +02:00
Annotation Fix CS 2014-06-25 08:52:01 +02:00
Command Fix DumpCommand to generate html with/out sandbox 2013-12-06 15:28:19 +05:30
Controller Fixed rendering issue when used with FOSRestBundle and configured to not 2012-08-23 15:09:56 +02:00
DependencyInjection Added request formats configuration 2014-05-18 21:25:30 +02:00
EventListener make form and validation extractors optional 2013-10-28 19:12:43 +01:00
Extractor Unified data types [actualType and subType] 2014-06-25 09:05:48 +02:00
Form/Extension Fixed BC Break from master (commit d072f35ea0 ) 2012-07-23 13:01:23 +03:00
Formatter Unified data types [actualType and subType] 2014-06-25 09:05:48 +02:00
Parser Unified data types [actualType and subType] 2014-06-25 09:05:48 +02:00
Resources Add documentation for tag property 2014-05-27 19:33:52 +02:00
Tests Unified data types [actualType and subType] 2014-06-25 09:05:48 +02:00
Twig/Extension Replace deprecated fork of dflydev's mardown library with the original one provided by Michel Fortin 2014-02-19 12:55:16 +01:00
Util abstracted docblock comment extraction, implemented in JmsMetadataParser to get parameter descriptions 2012-08-31 14:57:42 -04:00
.gitignore Added phpunit.xml to the ignore file 2012-05-23 00:43:18 +02:00
.travis.yml Simplified the Travis configuration 2014-06-17 19:01:48 +02:00
composer.json Replace deprecated fork of dflydev's mardown library with the original one provided by Michel Fortin 2014-02-19 12:55:16 +01:00
CONTRIBUTING.md Add a note about PR desc in CONTRIBUTING file 2013-11-14 12:07:19 +01:00
DataTypes.php Unified data types [actualType and subType] 2014-06-25 09:05:48 +02:00
NelmioApiDocBundle.php make form and validation extractors optional 2013-10-28 19:12:43 +01:00
phpunit.xml.dist Ignore vendor in code coverage 2012-04-13 15:21:45 +02:00
README.md Typo fix 2013-11-15 13:29:32 +03:00

README.md

NelmioApiDocBundle

Build Status

The NelmioApiDocBundle bundle allows you to generate a decent documentation for your APIs.

Important: This bundle is developed in sync with symfony's repository. For Symfony 2.0.x, you need to use the 1.* version of the bundle.

Documentation

For documentation, see:

Resources/doc/

Read the documentation

Contributing

See CONTRIBUTING file.

Running the Tests

Install the Composer dev dependencies:

php composer.phar install --dev

Then, run the test suite using PHPUnit:

phpunit

Credits

The design is heavily inspired by the swagger-ui project. Some icons from the Glyphicons library are used to render the documentation.

License

This bundle is released under the MIT license. See the complete license in the bundle:

Resources/meta/LICENSE