0

I am trying to document an akka-http API using swagger & swagger-akka-http. This blog post gave me a good start, but now I am stuck, trying to document the fact that the API is using basic auth.

what I have is:

@Path("/foo")
@Api(value = "/foo", produces = "application/json")
class FooService ...

@ApiOperation(value = "Get list of all foos", nickname = "getAllFoos", httpMethod = "GET",
response = classOf[Foo], responseContainer = "Set")
def getAll: Route = get {...

This generates a json which I can view in the swagger UI. However, I cannot use the generated examples, as the auth option is missing.

I have not found any examples using swagger-akka-http, only some using yaml config

In a yaml, this could look like this:

securityDefinitions:
  basicAuth:
    type: basic
    description: HTTP Basic Authentication.

however, I do not have a yaml. Nor do I have control over the generated .json except through the annotations.

IIUC, the correct place to mention the auth method is the authorizations parameter of the Api or ApiOperation annotations. This param should contain an array of Authorization annotations.

The value attribute of each Authorization annotation is supposed to reference a SecurityDefinitionObject

But I have no idea how to define this SecurityDefinitionObject using annotations.

The Authorization annotation is not supposed to be used standalone and is ignored if it is.

Is there something I have missed? Do I need an extra yaml or json file with additional declarations and where do I put it if I do? Something much more else?

Thank you

EDIT

With the 0.7.2-SNAPSHOT, the basicAuth array is being generated lie this: 

paths: {
    /foos: {
        get: {
        security: [
            {
            basicAuth: [ ]
            }
        ],

Now the only issue is to get the Swagger UI to interpret it correctly and use the auth in the examples. AFAIK, if you need basic auth in the UI, you have to add it yourself, like it is described here

kostja
  • 60,521
  • 48
  • 179
  • 224

1 Answers1

3

I currently maintain swagger-akka-http.

The code is pretty much a thin wrapper around swagger.io code base.

The @Api and @ApiOperation annotations support an authorizations param.

https://github.com/swagger-api/swagger-core/blob/master/modules/swagger-annotations/src/main/java/io/swagger/annotations/Api.java

@Api(value = "/myApi", description = "My API", produces = "application/json", 
authorizations=Array(new Authorization(value="basicAuth")))

I have never used this functionality but maybe you could try it out.

PJ Fanning
  • 953
  • 5
  • 13
  • I think I see what you are seeing in that @Api authorizations value don't appear to come out the swagger json. I've looked at the io.swagger.jaxrs.Reader class and it looks like it might provide what is needed. I can investigate adding support like the existing Info object support on the SwaggerDocService class in swagger-akka-http. – PJ Fanning Jul 15 '16 at 22:26
  • https://github.com/pjfanning/swagger-akka-http-sample/tree/api-authorizations has a modification demoing an @Api annotation with an authorization and that does get output in the swagger json (http://localhost:12345/api-docs/swagger.json). `"security": [{ "basicAuth": [] }],` – PJ Fanning Jul 15 '16 at 23:04
  • I've created a 0.7.2-SNAPSHOT version of swagger-akka-http which supports setting security definitions - https://github.com/pjfanning/swagger-akka-http-sample/tree/security-definitions shows the usage in a sample – PJ Fanning Jul 15 '16 at 23:57
  • Many thanks, with the 0.7.2-SNAPSHOT it works. Swagger UI is not cooperating though. Will have to tweak the UI code. – kostja Jul 17 '16 at 07:59