CODEWITHSUNDEEP
servicestackswaggerswagger-ui
Tyst
Tyst

Reputation: 871

ServiceStack + Swagger-UI [Api] Attribute Usage

I must be daft, but I cannot figure out what the usage of the [Api] attribute actually does for ServiceStack's SwaggerFeature.

Not tagging [Api] doesn't seem to influence whether or not the api shows up in Swagger and I cannot find a description rendered anywhere when using it like [Api("Service Description")]

My usage is like this:

[Api("Monkey Service Description")]
[Route("/zoo/monkey/{Id}", "GET", Summary = "Get MonkeyDocument by Id", Notes = "Returns a MonkeyDocument based on Id")]
public class GetMonkey : GetAnimal, IReturn<MonkeyDocument> // GetAnimal Has Id property
{
}

In Swagger-UI, the results show up on the page when expanded as:

/zoo              Show/Hide List Operations Expand Operations Raw

 + GET /zoo/monkey/{Id}                  Get MonkeyDocument by Id
      Implementation Notes
      Returns a MonkeyDocument based on Id

Upvotes: 1

Views: 1120

Answers (1)

Mike Mertsock
Mike Mertsock

Reputation: 12015

ApiAttribute is no longer used in any Swagger-related functionality. The only usage of it I could find is related to the metadata page.

Your use of RouteAttribute to describe the service endpoint is the correct way to document your routes in Swagger. You can browse the source of SwaggerApiService and its unit ests to learn more about what attributes, etc., can be used to document your APIs in Swagger.

Edit

Actually, as mentioned in the comments, the ApiAttribute Description value is being returned to the Swagger UI client. e.g. the JSON sent back from the initial Resources request looks something like:

{
  "swaggerVersion":"1.1",
  "basePath":"http://localhost/api",
  "apis":[
     {"path":"/resource/zoo","description":"Monkey Service Description"}, ...
  ]
}

This particular description value is separate from the Route attribute description values, which are rendered in the Swagger UI and are returned from a separate Ajax request. The ApiAttribute description values, though they are returned to the Swagger UI client and stored in a SwaggerResource object in swagger.js, don't seem to be displayed on the screen in any way. At least with the current version of Swagger used by ServiceStack.

Here's a screen shot that shows how the Api and Route attributes are used on the Metadata page for a given DTO. I set up two Routes for the same DTO class to show the difference:

enter image description here

Upvotes: 3

Related Questions