zircote/swagger-php — pull request #78 by steffkes (2013-05-04 14:36:15+00:00)
Title: accept external/global options for api-basepath, -version & swagger-version

PR for #76

This is a working patch, but it's just a suggesting. The idea itself contains two parts:

1) there is no longer the need to repeat some global specifications (like the apis basepath and the related version) on all resources. like described in #76, the projects i know are using multiple environments and all use different hostnames .. maybe not all have the same api-version available - so that may be a host/environment-specific information, therefore it's difficult to handle that in the code .. additionally it needs to be managed in multiple places, which makes me a bit sad :)

2) it provides the possibility to use external informations. @bfanger mentioned in his comment on https://github.com/zircote/swagger-php/issues/76#issuecomment-17368329 that he's using Constants to avoid repeating this informations - which is one possibility. i'd like to use information from f.e. git-tags to describe to api version .. the code itself does not contain that information, but while i deploy the project, that can be provided w/o a hassle.

The Command (assuming you're using the provided binary) could be something like:

vendor/bin/swagger \
-f \
-p . \
-e vendor/ \
-o public/docs/api \
--api-base-path="https://$api_hostname" \
--api-version="`date -u -Iseconds` ($git_ref)" \

To comment on @bfanger's thoughts:

> I don't think you'll need to change the Parser, just create Swagger::setApiVersion(), etc. methods and mutate the Swagger->registry. These methods could even be called after discoverServices()/constructor.

While i'm still thinking over this .. i guess your idea would be, create the registry and loop over the resources to set the value afterwards, no? Kinda like the loop which happens for `resolveModel` .. hm, yeah. the longer i think about it .. maybe we go with this one.

My initial thoughts were this ones: if you start with `Swagger::discover` from the provided binary, it will call `Swagger::__construct` and because you're using `$path` it will automatically call `Swagger::discoverServices` w/o any change to intercept this flow. Continuing from there, a new `Parser` is created, which executes `Parser::parse` directly from its own constructor. If a `T_CLASS`-Token is detected it jumps to `Parser::parseClass` -- where i've changed the code.

Like i already said, this is suggestions .. works for me, but may need additional tweaks here and there :)