问题
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.
回答1:
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.
- The two are not mutually exclusive
- 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:
- Here is a link to a Slate themed swagger UI
- Here is a project that generates Slate docs based on your Swagger definition
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).
回答2:
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
回答3:
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
回答4:
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.
来源：https://stackoverflow.com/questions/29469938/slate-vs-swagger-which-is-better-and-which-have-more-options