ApiResponses, ApiErrors, mustache template, maven-plugin

[bbcooper]

I am trying to render a confluence markup using maven plugin and my custom mustache template.

The latest dependency:

    <dependency>
        <groupId>com.wordnik</groupId>
        <artifactId>swagger-jaxrs_2.10</artifactId>
        <version>1.3.2</version>
    </dependency>

depends on swagger-core and in turn on swagger-annotations. The examples I saw about annotating the REST methods are using @ApiResponses and @ApiResponse which seems correct as @ApiErrors and @ApiError are not present anymore.

In my custom mustache template which is derived from https://raw.github.com/kongchen/api-doc-template/master/v1.1/wiki.mustache. This template includes a section

h4. Errors || Status Code || Reason || {{#errorResponses}} |{{code}}|{{{reason}}}| {{/errorResponses}}

which is giving me trouble.

My class is annotated with @ApiResponses( value = { @ApiResponse(code = 400, message = "Wrong paramaters were given for this services's method."), @ApiResponse(code = 404, message = "No bicikelj data found for given parameters.") })

and the above is not rendered even if I change the mustache template to something like:

|| HTTP Status || Description || {{#responses}} |{{code}}|{{{message}}}| {{/responses}}

Am I doing something wrong or is there a bug?

Regards

[bbcooper]

After reading https://github.com/wordnik/swagger-core/wiki/1.2-transition I also tried:

|| HTTP Status || Description || {{#responseMessages}} |{{code}}|{{{message}}}| {{/responseMessages}}

but failed.

[kongchen]

Currently, the plugin does not support 1.3.2, it only supports 1.2.x by now. @ApiResponses and @ApiResponse are 1.3.2 and @ApiErrors and @ApiError are deprecated in 1.3.x, so you cannot get your errors in output.

I'm trying to support it

[bbcooper]

Thanks for quick reply!

As I am new to swagger, will I miss something important if I use 1.2.x? I am currently only using maven plugin for generating confluence templates.

[kongchen]

That depends on your requirements, if 1.2.x can express everything you need and it's enough for you. If you need to express more (such as Oauth), you should use 1.3.x and this plugin would not help you by now.

2014/1/21 Borut Bolčina notifications@github.com

Thanks for quick reply!

As I am new to swagger, will I miss something important if I use 1.2.x? I am currently only using maven plugin for generating confluence templates.

— Reply to this email directly or view it on GitHubhttps://github.com/kongchen/swagger-maven-plugin/issues/31#issuecomment-32864674 .

Regards, Kong

[bbcooper]

Thanks,

I switched to

<dependency>
        <groupId>com.wordnik</groupId>
        <artifactId>swagger-jaxrs_2.10.0</artifactId>
        <version>1.2.5</version>
    </dependency> 

for now and making some progress.

I wonder if you can help me out on two template variables and how they are initialized - with annotations?

responseHeader and samples, What annotatinos do I have to use for

{{#responseHeader}} h4. Response Headers || Header || Type || Standard || Required || Description || {{#paras}} | {{name}} | {{type}} | yes | {{required}} | {{{description}}} {{/paras}} {{/responseHeader}}

{{#samples}} h3. Examples {{/samples}} {{#samples}}

{quote}{{{sampleDescription}}}{quote}

Request {code}{{{sampleRequest}}} {code} Response {code} {{{sampleResponse}}} {code} {{/samples}}

Best regards, borut

[kongchen]

I didn't find any way to document responseHeader in swagger, so I did a trick in this plugin, you can refer to https://github.com/kongchen/swagger-maven-plugin/blob/master/src/test/java/sample/api/car/CarResourceV1.java#L25, the plugin can recognize that and output your response headers in your final doc.

For sample* annotations, I have to say they're experimental, and they're not supported by this plugin. Actually, they're used by another swagger doc generate tool: https://github.com/kongchen/ginger, the tool uses the same template as the plugin, you can try it out if you've interest.

[bbcooper]

Thanks for the explanations.

Having an example in a documentation is a real benefit, I have always insisted that people write javadoc on rest interfaces where an example call is a mandatory part of the rest api documentation. I guess we could use ApiOperation notes for example call, I'll try that to see how it looks.

Now I have some more issues to report, but I guess it would be appropriate to open new issue for each.

[kongchen]

OK, thanks