35

I have to document my API's. I have to use any one of them Slate Or Swagger. I want to know which one have more options, pros and cons, which one is better.

Sariban D'Cl
  • 2,197
  • 2
  • 28
  • 42

4 Answers4

58

Swagger and Slate serve two different purposes. Swagger is an attempt at a standardized way of describing a RESTful API (similar, for example, to ApiBlueprint)

Swagger is a JSON based API definition format, which allows for the description of REST APIs.

~ API Design Tooling From Swagger

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

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

The goal of Swagger is to provide a standard upon which others can build extensive tooling (for example: documentation, API explorers, mock servers, code generation, testing utilities etc.). See, for example: Swagger Tooling

More to your question: Some Slate tooling for swagger:

So the two are not mutually exclusive, but to your direct question: Implementing Swagger will give you more options and greater flexibility (was well as the ability to also generate Slate documentation).

toast38coza
  • 8,650
  • 3
  • 39
  • 32
  • 6
    Swagger2Slate is no-longer maintained and seems to have several outstanding issues. https://github.com/mermade/widdershins is a Node.js based Swagger/OpenApi spec to Slate markdown converter. Disclosure, I am the author. – MikeRalphson Oct 24 '16 at 15:56
  • Even with different purposes hatcommunity switched from swagger to slant for example: http://forum.hatcommunity.org/t/api-documentation-publishing-slate-vs-swagger/69 – gandra404 Jan 10 '17 at 06:44
5

About Slate:
- API documentation Template/Framework
- looks good
- ease of use
- Syntax highlighting
- Language Specific – Tabbed
- Page Search
- 3 columned customizable layout
- We can create table
- Scrollable links to each and every blocks/methods/headings
- Alert Facility [3 types] – warning, success, notice
- Tables for http error codes
- Markdown syntax
- We can use Site logo
- Demo

About Swagger:
- It gives us API access inside the docs itself, where we can check the response for any particular request.
- It gives a clear picture of API responds with their parameters and options.
- YAML based format
- Not suited for hypermedia API
- There is no Design tooling for Swagger
- Responses are in XML or JSON
- Swagger JS -- JavaScript library to connect to swagger-enabled APIs via browser or nodejs
- Swagger Node Express -- Swagger module for node.js express module
- It has swagger UI framework
- Demo

naXa stands with Ukraine
  • 35,493
  • 19
  • 190
  • 259
Sariban D'Cl
  • 2,197
  • 2
  • 28
  • 42
4

From my point of view, those tools have very different purposes. Swagger is a description language, while slate is just for documentation.

I've used swagger to create a descriptionn, from which i can autogenerate different clients for my API, even autogenerate documentation.

You can also create Markdown from the swagger spec, and the use those markdowns in Slate. [1]

[1] https://github.com/RobWin/swagger2markup

Neoecos
  • 569
  • 4
  • 16
1

I make slate-flask(https://github.com/AhnSeongHyun/slate-flask) based on python-flask.

features:

  • Configuration File(config.json) : Set title, programming language for example codes using config.json base on JSON Format. Also set the path of the API documents and TOC(Table of contents).

  • Support Multi-API documents : Original Slate support one API document based on Markdown format. But slate-flask support multi-API documents for efficient management and amount of documents using TOC(index.json).

  • Support dynamic changes of documents : You can reflect the changes of API documents without restarting server. When web page refresh, if exist changes, slate-flask reload API documents. Users only focus on writing API documents.

ash84
  • 787
  • 3
  • 12
  • 33