Can't emit both description and summary to OpenAPI

[nguerrera]

OpenAPI 2 and 3 have distinct summary and description fields, but we only have one @doc so there's no way to use both. When something takes a summary and description, we seem to use @doc as summary. And when it only takes a description we use @doc as description.

[markcowl]

• add @summary decorator in core to support the summary scenario
• ensure that @doc is placed in description in openAPI emitters.