Slate vs Swagger - Which is better and which have more options? [closed]

一世执手 提交于 2019-12-02 16:41:16

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).

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

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

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.

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!