Search code examples
phpswaggerslimswagger-php

swagger-php having different documentations from the same code

We are using slim framework and swagger-php to dynamically generate the swagger documentation. We now have some special methods in the API that should not be publicly documentated. (/doc now) Is there any way I can have a second documentation url (/doc2) where I can get the secret methods and params documentated? (without having to make the documentation by hand, just using the annotations in the php code). Thanks.

Solution

  • As per the latest version of swagger-php you can indicate a list of files and/or directories to exclude from scanning when building the documentation.

    See the scan function's docblock on github for details.

    A solution to your problem is to separate the public and private methods into different files. Then create two documentation generation methods/functions each excluding the other's files.

    Example:

    $privateOptions = array(
    'exclude' => array('app/api/public')
);
$privateDoc = Swagger\scan("app/", $privateOptions);
...
$publicOptions = array(
    'exclude' => array('app/api/private')
);
$publicDoc = Swagger\scan("app/", $publicOptions);

    Note: This example is indicative and not tested, you can also exclude filenames.