Generate swagger docus from java Annotations, missing security definitions

2
votes

I use the swagger maven plugin to generate the swagger documentation at build time.

This works fine for the basic @SwaggerDefinition annotations. But the sub-part securityDefinition is not generated in the final json and yaml files.

I'm using swagger-maven-plugin in version 3.1.4

Any ideas what might be missing?

@SwaggerDefinition(
        info = @Info(
                description = "Interact with example",
                version = "V1.1.0",
                title = "The example API",
                termsOfService = "http://example.com",
                contact = @Contact(
                   name = "André Schild", 
                   email = "[email protected]", 
                   url = "http://example.com"
                ),
                license = @License(
                    name = "example License",
                    url = "http://example.com/"
                )
        ),
        host = "api.example.com",
        basePath = "/api/v1",
        consumes = {"application/json"},
        produces = {"application/json"},
        schemes = {SwaggerDefinition.Scheme.HTTPS},
        securityDefinition = @SecurityDefinition(
                basicAuthDefinions = {
                        @BasicAuthDefinition(key = "basicAuth")},
                apiKeyAuthDefintions = {
                        @ApiKeyAuthDefinition(key = "exampleAuth", name = "apiKey", in = ApiKeyLocation.HEADER)}),
          tags = {
                @Tag(name = "API", description = "Api for example"),
                @Tag(name = "V1", description = "V1 Api for example")
        }, 
        externalDocs = @ExternalDocs(
                value = "example",
                url = "http://example.com"
        )
)

Here what the final swagger file looks like:

---
swagger: "2.0"
info:
  description: "Interact with example"
  version: "V1.1.0"
  title: "The example API"
  termsOfService: "http://example.com"
  contact:
    name: "André Schild"
    url: "http://example.com"
    email: "[email protected]"
  license:
    name: "example License"
    url: "http://example.com/"
host: "api.example.com"
basePath: "/api/v1"
tags:
- name: "categories"
  description: "Operations about categories"
paths:
  /categories:
    get: 
.... and more paths/definitions....
3
javamavenannotationsswagger

3 Answers

1
votes

The way I got this working for me was by creating a separate class/interface and annotating it with @SwaggerDefinition with the security definitions. And it provided the security definition for all the APIs.

Like this:

@SwaggerDefinition(securityDefinition = @SecurityDefinition(apiKeyAuthDefinitions = { @ApiKeyAuthDefinition(key = "ApiKey", name = "Authorization", in = ApiKeyLocation.HEADER) }))
public interface SwaggerSecurityDefinition {

}
0
votes

@Andre:

to get the solution of ritesh working you need to include the security definition in your resource classes:

@Api(value = "/example", description = "", authorizations = {
        @Authorization(
                value = "ApiKey"
        )
})
public class ExapleResource {
...
}

or you could use the swagger bean to configure the definitions globally. A good example is found in the swagger-examples

0
votes

Configure swagger-maven-plugin if using it (https://github.com/kongchen/swagger-maven-plugin):

<securityDefinition>
    <name>MybasicAuth</name>
    <type>basic</type>
</securityDefinition>