use custom javadoc tag for summary property in swagger operations

[roeltje25]

Swagger has a description and a summary line. In e.g. swagger ui the summary line is shown on the right of the operation header and the description line is added to the body under "Implementation Notes". Perhaps jaxrs analyzer could introduce a custom javadoc tag to provide the summary line. E.g.

/**
 * @jaxrs.summary This is an operation
 */

This type of tags could be used for other additions as well of course. Think of

/**
 * @jaxrs.response 401 if no valid authorization token is provided
 */

which could map to the response codes. Jaxrs analyzer can analyze those codes automatically in case of returning Response objects, but e.g. with crosscutting concerns such as security where one would use a ContainerRequestFilter this does not get picked up.

[rmpestano]

this is something nice to have, in JaxRS-doclet there was such feature to document response codes

:+1:

[sdaschner]

Nice idea of overriding / enhancing the results of the default analysis. My own priorities are more focused to improve the Bytecode analysis results, but as always -> feel free to PR :-)

[sdaschner]

@roeltje25 If you would like to contribute and I can help with anything regarding code, please let me know!

[peter-janssen]

I like to weigh in here as well. For me the swagger example fields are particularly interesting. Enunciate has already implemented this in a way. I already looked at the code a while back for this but I couldn't really understand what is already there. Some javadoc tags are already read, right?

[sdaschner]

Yes, currently the @param tags are read and the HTTP information (status codes, header fields) are taken from the Bytecode analysis.

[rmpestano]

Yes and thats great! although it is not working with ResponseBuilder:

    /**
     * Finds a car based on its ID
     * @param id car ID
     */
    @GET
    @Path("/{id:[0-9][0-9]*}")
    public Response findById(@PathParam("id") Integer id, @Context Request request,@Context HttpHeaders headers) {
        Car entity;

        try {
            entity = carService.findById(id);
        } catch (NoResultException nre) {
            entity = null;
        }

        if(entity == null){
            return Response.status(Status.NOT_FOUND).build();
        }

        CacheControl cc = new CacheControl();
        cc.setMaxAge(100);
        EntityTag tag = new EntityTag(Integer.toString(entity.hashCode()));
        Response.ResponseBuilder builder =  request.evaluatePreconditions(tag);
        if(builder != null){
            builder.cacheControl(cc);
            return builder.build();
        }
        builder = Response.ok(entity);
        builder.cacheControl(cc);
        builder.tag(tag);
        return builder.build();
    }

Here's swagger ui result:

And also not integrated with exception mappers , example (on javadoc are the statuses I am expecting):

/**
     * Creates a new car
     * @status 400 Car model cannot be empty
     * @status 400 Car name cannot be empty
     * @status 400 Car name must be unique
     * @status 201 Car created successfully
     */
    @POST
    @Consumes("application/json")
    public Response create(Car entity) {
        carService.insert(entity);
        return Response.created(UriBuilder.fromResource(CarEndpoint.class).path(String.valueOf(entity.getId())).build()).build();
    }

Where carService.insert(entity); throws some exception being catch by exception mappers which turn them into JaxRS responses.

[sdaschner]

Related to #130