search

erunion / mill

☴ An annotation-based DSL for documenting a REST API.
MIT License
39 stars 2 forks source link

Support referencing a representation by its label #68

Open erunion opened 7 years ago

erunion commented 7 years ago

With the new MSON work in #42, the syntax for referencing another representation in a representation data is:

@api-data director (\Mill\Examples\Showtimes\Representations\Person) - Director

This is fine, but it's a bit... wordy. It would be nice if instead of that you could just do:

@api-data director (Person) - Director

Where Person is being pulled from the @api-label annotation atop the \Mill\Examples\Showtimes\Representations\Person class.

The major problem I see with handling this is that this would require that we parse out representations first, so we have that label data in memory for lookups.

erunion commented 7 years ago

Might also be worth extending this to all instances where you'd reference a representation (@api-return, @api-throws, and possibly @api-warning (#70).

erunion commented 7 years ago

Doing this'll also help us to remove our dependency on PHP namespacing. https://github.com/vimeo/mill/issues/17

erunion commented 7 years ago

@api-return and @api-throws are getting a new MSON-like syntax with this change:

Old:

@api-return:public {object} \Mill\Examples\Showtimes\Representations\Theater @api-throws:public {404} \Mill\Examples\Showtimes\Representations\Error If the movie could not be found. @api-throws:public {404} \Mill\Examples\Showtimes\Representations\CodedError (\Mill\Examples\Showtimes\Representations\CodedError::DISALLOWED) +BUY_TICKETS+ {movie,theater}

New:

@api-return:public (object, Theater) @api-throws:public (404, Error) If the movie movie could not be found. @api-throws:public (404, Coded Error, 666, BUY_TICKETS) {movie,theater}

This also means that we'll no longer support any FQDN error codes. Unfortunate, but necessary to move past just supporting PHP.