1

From this question I have seen that

Swagger and Slate serve two different purposes. Swagger is an attempt at a standardized way of describing a RESTful API.

Slate, on the other hand is a pretty theme for writing nice API docs.

It further states that

The two are not mutually exclusive Ideally, one should generate your slate documentation from your Swagger API description

I am a bit confused. Why would I need slate when I already have Swagger UI like so.

What more do I need to ‘document’ ? I am genuinely asking because as I said I am a bit confused by their uses.

Community
  • 1
  • 1
YulePale
  • 6,688
  • 16
  • 46
  • 95

1 Answers1

1

There are a few things that are worth mentioning when creating documentation for a new API.

Swagger provides a really nice graphical interface for exploring the endpoints of an API, but there are still other things that should be included in your documentation, including (but not limited to):

  1. Authentication methods (OAuth/JWT, Basic Auth, Cookie/Session, Apikey/token)
  2. Date formats for date output + timezone
  3. Filtering/pagination/selecting/sorting settings for the API
  4. Which environments exists (usually test, pre-production and production) including their differences.
  5. Error handling including error codes, exception types and logging
  6. Potential rate limits for your API
  7. Terms and conditions for using your API
Daniel
  • 10,641
  • 12
  • 47
  • 85
  • So slate is for the additional info and swagger for experimenting and exploring the apis? – YulePale May 26 '19 at 15:49
  • 1
    That is a possibility, but swagger has improved a lot since the answer you were referring to was written (september 2015). Today you can also add additional info directly with swagger-ui. You can read more on swaggers website :) https://swagger.io/blog/api-documentation/api-documentation-swagger-ui/ – Daniel May 26 '19 at 15:51
  • My concern is with swagger-hub and at what point will I pay for it? Can I host the swagger api myself or do I need to always use the Swagger UI? Lastly, in your own opinion does one need slate now that swagger has improved? – YulePale May 26 '19 at 15:54
  • 1
    In my opinion you can make it work without Slate. I've used Slate at one point, but it seems that Swagger's improvements has taken the punch out of Slate. Their GitHub repo shows that the last commit was 11 months ago https://github.com/lord/slate – Daniel May 26 '19 at 16:04