初衷

记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情。也许多点,也许少点。甚至,接口总是需要适应新需求的,修改了,增加了,这份文档维护起来就很困难了。于是发现了swagger,自动生成文档的工具。

swagger介绍

首先,官网这样写的:

Swagger – The World's Most Popular Framework for APIs.

因为自强所以自信。swagger官方更新很给力,各种版本的更新都有。swagger会扫描配置的API文档格式自动生成一份json数据,而swagger官方也提供了ui来做通常的展示,当然也支持自定义ui的。不过对后端开发者来说,能用就可以了,官方就可以了。

最强的是,不仅展示API,而且可以调用访问,只要输入参数既可以try it out.

效果为先,最终展示doc界面,也可以设置为中文:

针对python flask的swagger客户端:

flask-swagger

A Swagger 2.0 spec extractor for Flask

Install:

pip install flask-swagger

Flask-swagger provides a method (swagger) that inspects the Flask app for endpoints that contain YAML docstrings with Swagger 2.0 Operation objects.

class UserAPI(MethodView):

    def post(self):
"""
Create a new user
---
tags:
- users
definitions:
- schema:
id: Group
properties:
name:
type: string
description: the group's name
parameters:
- in: body
name: body
schema:
id: User
required:
- email
- name
properties:
email:
type: string
description: email for user
name:
type: string
description: name for user
address:
description: address for user
schema:
id: Address
properties:
street:
type: string
state:
type: string
country:
type: string
postalcode:
type: string
groups:
type: array
description: list of groups
items:
$ref: "#/definitions/Group"
responses:
201:
description: User created
"""
return {} 可以参考:https://github.com/gangverk/flask-swagger 针对Java spring mvc的可以看这里:http://www.cnblogs.com/woshimrf/p/5863318.html 针对swagger yaml本身的一些介绍:https://www.gitbook.com/book/huangwenchao/swagger/details

使用swagger作为restful api的doc文档生成——从源码中去提取restful URL接口描述文档的更多相关文章

  1. 关于android源码中的APP编译时引用隐藏的API出现的问题

    今天在编译android源码中的计算器APP时发现,竟然无法使用系统隐藏的API,比如android.os.ServiceManager中的API,引用这个类时提示错误,记忆中在android源码中的 ...

  2. 【百度地图API】多家地图API内存消耗对比测验(带源码)

    原文:[百度地图API]多家地图API内存消耗对比测验(带源码) 任务描述: 啊,美妙的春节结束了.酸奶小妹和妈妈的山西平遥之旅也宣告成功!距离平遥古城7km,有一个同样身为“世界文化遗产”的寺庙,叫 ...

  3. 是否应该学习qt源码(碰到问题的时候,或者文档对函数描述不清楚的时候,可以看一下)

    是否应该学习qt源码 如果你想调用某个函数,但是文档并没有清晰描述这个函数的功能的时候,你就需要去阅读源码,看看Qt究竟是怎么实现的.比如用QNetworkAccessManager发送一个QHttp ...

  4. 使用swagger作为restful api的doc文档生成

    初衷 记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情.也许多点,也许少点.甚至,接口总是需要适应新需求的,修改了,增加了,这份 ...

  5. nova创建虚拟机源码分析系列之一 restful api

    开始学习openstack源码,源码文件多,分支不少.按照学习的方法走通一条线是最好的,而网上推荐的最多的就是nova创建虚机的过程.从这一条线入手,能够贯穿openstack核心服务.写博文仅做学习 ...

  6. 使用Java生成word文档(附源码)

    当我们使用Java生成word文档时,通常首先会想到iText和POI,这是因为我们习惯了使用这两种方法操作Excel,自然而然的也想使用这种生成word文档.但是当我们需要动态生成word时,通常不 ...

  7. Doxygen自动文档生成工具在Eclipse中的集成及使用举例

    你有为软件编写说明文档的苦恼吗?当别人甩给你一个庞大的系统,让你根据里面的代码注释理解后写出一份完整的开发文档,你会怎么办?一个个的看代码 然后耗时N天来写吗?这既是一份苦差事也极其耗时,有没有更好的 ...

  8. 源码分析 Alibaba sentinel 滑动窗口实现原理(文末附原理图)

    要实现限流.熔断等功能,首先要解决的问题是如何实时采集服务(资源)调用信息.例如将某一个接口设置的限流阔值 1W/tps,那首先如何判断当前的 TPS 是多少?Alibaba Sentinel 采用滑 ...

  9. 最长(大)回文串的查找(字符串中找出最长的回文串)PHP实现

    首先还是先解释一下什么是回文串:就是从左到右或者从右到左读,都是同样的字符串.比如:上海自来水来自海上,bob等等. 那么什么又是找出最长回文串呢? 例如:字符串abcdefedcfggggggfc, ...

随机推荐

  1. Django - ModelForm组件

    一.ModelForm组件 这是一个神奇的组件,通过名字我们可以看出来,这个组件的功能就是把model和form组合起来,先来一个简单的例子来看一下这个东西怎么用:比如我们的数据库中有这样一张学生表, ...

  2. web 开发常见问题--Session 与 Cookie 却别

    总结: 1.首先,session与cookie都是保存数据的,存在的原因很大程度上是为了解决HTTP协议的无状态特性 2.都是保存数据,却别在于cookie保存在客户端,由浏览器管理,session保 ...

  3. 分布式计算hadoop三大组件

    设计原则:移动计算,而不是移动数据 计算层:Map/Reduce调度层:YARN数据层:HDFS 这三层之间没有必然的依赖性,只是经常这么搭配,而且都是hadoop那个包里一起安装的,三层都可以独立运 ...

  4. tensorflow 中 softmax_cross_entropy_with_logits 与 sparse_softmax_cross_entropy_with_logits 的区别

    http://stackoverflow.com/questions/37312421/tensorflow-whats-the-difference-between-sparse-softmax-c ...

  5. go——常量

    常量是一个简单值的标识符,在程序运行时,不会被修改的量常量中的数据类型只可以是布尔值.数字型(整数型.浮点型和复数)和字符串.常量的定义格式: const identifier [type] = va ...

  6. Delphi 正则表达式之TPerlRegEx 类的属性与方法(6): EscapeRegExChars 函数

    Delphi 正则表达式之TPerlRegEx 类的属性与方法(6): EscapeRegExChars 函数 // EscapeRegExChars 函数可以自动为特殊字符加转义符号 \ var   ...

  7. 微信小程序组件button

    表单组件button:官方文档 Demo Code: var types=['default', 'primary', 'warn']; var pageObject = { data: { defa ...

  8. Kattis - glitchbot 【DFS】

    Kattis - glitchbot [DFS] 题意 有一个机器人 刚开始在(0, 0),然后给出一个目标点,并且会给出一系列指令,但是其中会有一个指令是错误的.我们需要找出那个指令,并且改成正确的 ...

  9. Matlab 使用的一些常用技巧

    主要是编程过程中遇到的一些问题和解决,大多数都是来自于Matlab文档.随时总结: Vectorization 向量化是Matlab作为一种专注数值.矩阵计算的语言,和其他语言的一个差别.这也是Mat ...

  10. OpenGL核心技术之Gamma校正

    笔者介绍:姜雪伟,IT公司技术合伙人,IT高级讲师,CSDN社区专家,特邀编辑,畅销书作者,国家专利发明人;已出版书籍:<手把手教你/2.2次幂.Gamma校正后的暗红色就会成为(0.5,0.0 ...