search

springfox / springfox-javadoc

Ability to use Javadoc for documentation for generating OpenAPI specifications
Apache License 2.0
17 stars 15 forks source link

Support "summary" field for ApiOperations #6

Open metacubed opened 6 years ago

metacubed commented 6 years ago

The Swagger 2.0 spec supports two fields on @ApiOperation: "summary" and "notes". In the current implementation, we set only the "notes" using the entire value of the comment.

However, the Javadoc spec also supports a summary and a description. From the Javadoc tech notes:

First Sentence The first sentence of each documentation comment should be a summary sentence that contains a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first block tag. The javadoc command copies this first sentence to the member summary at the top of the HTML page.

Using this spec, we can provide both "summary" and "notes" for @ApiOperation. It can also be used on class docs to specify @Api "tags".

@dilipkrish, do you think this is a good approach? I can help with implementing this if you don't foresee any issues.

neumaennl commented 6 years ago

Hi, I'm one of the original authors of springfox-javadoc. I just had to delete my company account because I no longer work for the company. This is my private account. This sounds like a good idea to me. I'd say go ahead and submit a pull request.