I pulled the Scalatra examples from Github and ran the Swagger example for Scalatra version 2.3. The example runs, but the API documentation is not generated completely. I was using the example as is.

When I call http://localhost:8080/api-docs in the browser I get the following result:

{
   "apiVersion":"1",
   "swaggerVersion":"1.2",
   "apis":[
      {
         "path":"/flowers",
         "description":"The flowershop API. It exposes operations for browsing and searching lists of flowers"
      }
   ],
   "authorizations":{
   },
   "info":{
      "title":"The Flowershop API",
      "description":"Docs for the Flowers API",
      "termsOfServiceUrl":"http://scalatra.org",
      "contact":"apiteam @ scalatra.org",
      "license":"MIT",
      "licenseUrl":"http://opensource.org/licenses/MIT"
   }
}

I also dubbel checked if the Scalatra 2.2 version works (which is part of the same examples package), but it generates even less:

{
   "basePath":"http://localhost:8080",
   "swaggerVersion":"1.0",
   "apiVersion":"1",
   "apis":[
      {
         "path":"/api-docs/flowers.{format}",
         "description":"The flowershop API. It exposes operations for browsing and searching lists of flowers"
      }
   ]
}

I posted an issue to the Scalatra issues list on Github and was lucky enough to get a quick response from casualjim the author of the Swagger examples. His response was:

That swagger looks correct.

You want to see the docs for the flowers endpoint? then request http://localhost:8080/api-docs/flowers

It’s only in the very new swagger 2.0 that you would see your entire api in the first json document.

Using the suggested URL does show the correct swagger documentation. Howevver, I find it strange/confusing that the setup does not work in the swagger UI:

• As suggested in the Scalatra swagger documentation I used the URL http://localhost:8080/api-docs/resources.json in the swagger UI.
• A link to the flowers API is listed when the http://localhost:8080/api-docs/resources.json is entered into the URL field.
• When I click on the link of the flowers API it does not display the flowers API.
• I cannot imagine that I have to enter the flowers API URL into the URL field.

Is this the correct behavior? Any suggestions how this can be solved?