Swagger是一种Rest API的表示方式。

有时也可以作为Rest API的交互式文档,描述形式化的接口描述,生成客户端和服务端的代码。

一,描述语言:Spec

Swagger API Spec是Swagger用来描述Rest API的语言。

API 可以是使用yaml或json来表示。

Swagger API Spec包含以下部分:

swagger,指定swagger spec版本
info,提供API的元数据
tags,补充的元数据,在swagger ui中,用于作为api的分组标签
host,主机,如果没有提供,则使用文档所在的host
basePath,相对于host的路径
schemes,API的传输协议,http,https,ws,wss
consumes,API可以消费的MIME类型列表
produces,API产生的MIME类型列表
paths,API的路径,以及每个路径的HTTP方法,一个路径加上一个HTTP方法构成了一个操作。每个操作都有以下内容:
tags,操作的标签
summary,短摘要
description,描述
externalDocs,外部文档
operationId,标识操作的唯一字符串
consumes,消费的MIME类型列表
produces,生产的MIME类型列表
parameters,参数列表
responses,应答状态码和对于的消息的Schema
schemes,传输协议
deprecated,不推荐使用
security,安全
definitions,定义API消费或生产的数据类型,使用json-schema描述,操作的parameter和response部分可以通过引用的方式使用definitions部分定义的schema
parameters,多个操作共用的参数
responses,多个操作共用的响应
securityDefinitions,安全scheme定义
security,安全声明
externalDocs,附加的外部文档

一个操作描述的实例:

/pets/findByTags:
get:
tags:
- pet
summary: Finds Pets by tags
description: Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.
operationId: findPetsByTags
produces:
- application/json
- application/xml
parameters:
- in: query
name: tags
description: Tags to filter by
required: false
type: array
items:
type: string
collectionFormat: multi
responses:
"200":
description: successful operation
schema:
type: array
items:
$ref: "#/definitions/Pet"
"400":
description: Invalid tag value
security:
- petstore_auth:
- write_pets
- read_pets

二,Swagger UI

Swagger UI用于显示Rest接口文档。

访问在线Swagger UI:http://petstore.swagger.io/

如何使用?只要把github项目(https://github.com/swagger-api/swagger-ui)下载到本地:。然后用浏览器打开dist/index.html就可以。

git clone https://github.com/swagger-api/swagger-ui.git

ps:swagger ui支持中文版。方法是修改index.html,在head标签中添加如下代码,引入/lang/zh-cn.js

<script src='lang/translator.js' type='text/javascript'></script>
<script src='lang/zh-cn.js' type='text/javascript'></script>

三,编辑器

Swagger Editor是Swagger API Spec的编辑器,Swagger Editor使用yaml进行编辑,但允许导入和下载yaml 和 json两种格式的文件。

下载发布版:https://github.com/swagger-api/swagger-editor/releases/download/v2.10.1/swagger-editor.zip

解压,然后用HTTP Server将静态文件加载起来,下面是安装node.js的http server并跑起来的指令

npm install -g http-server
wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.1/swagger-editor.zip
unzip swagger-editor.zip
http-server -p 8080 swagger-editor

在浏览器中输入地址就可以进行编辑了

https://zhuanlan.zhihu.com/p/21353795

API的描述语言--Swagger的更多相关文章

  1. Spring Data REST API集成Springfox、Swagger

    原文: Documenting a Spring Data REST API with Springfox and Swagger 使用Spring Date REST,你可以迅速为Spring Da ...

  2. API生命周期第三阶段:API实施:使用swagger codegen生成可部署工程,择取一个作为mock service

    在分享培训了swagger对于API的设计之后,有一些人问我说:你看,现在咱们前端使用web_API做为mock data在进行测试,后端也有mock 测试.然后我们再进行联调,这之中肯定会出现一些偏 ...

  3. Blazor 002 : 一种开历史倒车的UI描述语言 -- Razor

    Razor是一门相当怪异丑陋的标记语言,但在实际使用中却十分高效灵活.本文主要介绍了Razor是什么,以及Razor引擎的一些浅薄的背后机理. 写文章前我本想一口气把Razor的基本语法,以及Blaz ...

  4. 硬件描述语言Verilog设计经验总结

    一.硬件描述语言Verilog 粗略地看Verilog与C语言有许多相似之处.分号用于结束每个语句,注释符也是相同的(/* ... */和// 都是熟悉的),运算符"=="也用来测 ...

  5. API文档工具-Swagger的集成

    最近安装了API文档工具swagger,因为Github上已有详细安装教程,且安装过程中没有碰到大的阻碍,所以此文仅对这次安装做一份大致记录 相关网站 Swagger 官方地址: http://swa ...

  6. WSDL(Web服务描述语言)详细解析(全文转载学习用)

    WSDL (Web Services Description Language,Web服务描述语言)是一种XML Application,他将Web服务描述定义为一组服务访问点,客户端可以通过这些服务 ...

  7. WSDL(WebService描述语言)文件介绍

    一.WSDL 1.WSDL 文档的组成部分 <portType>:web service 执行的操作 <message>:web service 使用的消息 <types ...

  8. 上一步是硬件描述语言,下一步是FPGA

    上一步是硬件描述语言,下一步是FPGA. 学习了硬件描述语言(Verilog或者VHDL)之后,FPGA该如何继续. 世上没有捷径,每一步都得踏踏实实的走.学习FPGA也是这样,在有了硬件描述语言的基 ...

  9. 使用Jena RDF API 开发脚本语言管理资源描述框架模型

    摘要 资源描述框架(Resource Description Framework RDF)是一种以XML格式描述元数据的标准格式.Jena是一种用于将关系数据库或是文本文件中所表示的数据建立为元数据模 ...

随机推荐

  1. 18.Linux磁盘管理

    1.磁盘分区工具fdisk 1. 添加一块小于2TB的磁盘进行使用,步骤如下: 给虚拟机添加一块新的硬盘 使用fdisk进行分区 使用mkfs进行格式化 使用mount进行挂载 PS: 生产分区建议, ...

  2. C# 添加、修改、删除Excel图表数据标签

    图表中,图表数据标签以数据化形式表现图表中的特定数据,可增强图表的可读性.我们可以对图表添加数据标签,也可以对已有的数据标签进行修改或者删除,下面将通过C#代码形式来实现. 使用工具:Spire.XL ...

  3. LaTeX常用篇(一)---公式输入

    目录 1. 序言 2. 命令介绍 3. 公式输入 3.1 无编号公式 3.2 有编号公式 更新时间:2019.10.02 1. 序言   当我们首次在文档中输入公式的时候,我们首先想到的是word,毕 ...

  4. MacOs mysql 安装

    1. 去官网下载mysql镜像:https://dev.mysql.com/downloads/file/?id=475582 2.  双击镜像文件 - >  双击.pkg文件 -> 出现 ...

  5. 使用SQLserver Management Studio连接VS2012自带数据库

    下载 Microsoft® SQL Server® 2008 Management Studio Express http://www.microsoft.com/zh-CN/download/det ...

  6. 网络数据请求request

    关于网络数据请求的类很多,httpwebrequest,webrequest,webclient以及httpclient,具体差别在此不在赘述,在应用方面介绍webclient与httpclient则 ...

  7. SpringBoot整合Redis(一)

    docker启动redis docker run -p 6379:6379 --name myredis redis 查看容器 [root@topcheer ~]# docker ps -l CONT ...

  8. Linux进程组和会话

    Linux的进程相互之间有一定的关系.比如说,在Linux进程基础中,我们看到,每个进程都有父进程,而所有的进程以init进程为根,形成一个树状结构.我们在这里讲解进程组和会话,以便以更加丰富的方式了 ...

  9. RESTFul API最佳实践

    RESTful API最佳实践 RESTful API 概述 基本概念 REST 英文全称:Representational State Transfer,直译为:表现层状态转移.首次是由Roy Th ...

  10. (Java) JWT-TokenUtils

    package com.vcgeek.hephaestus.utils; import com.auth0.jwt.JWT; import com.auth0.jwt.JWTVerifier; imp ...