In what scenario would Slate and Swagger be used together?

Question

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.

Answer 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