使用swagger作为restful api的doc文档生成——从源码中去提取restful URL接口描述文档
初衷
记得以前写接口,写完后会整理一份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:
- 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接口描述文档的更多相关文章
- 关于android源码中的APP编译时引用隐藏的API出现的问题
今天在编译android源码中的计算器APP时发现,竟然无法使用系统隐藏的API,比如android.os.ServiceManager中的API,引用这个类时提示错误,记忆中在android源码中的 ...
- 【百度地图API】多家地图API内存消耗对比测验(带源码)
原文:[百度地图API]多家地图API内存消耗对比测验(带源码) 任务描述: 啊,美妙的春节结束了.酸奶小妹和妈妈的山西平遥之旅也宣告成功!距离平遥古城7km,有一个同样身为“世界文化遗产”的寺庙,叫 ...
- 是否应该学习qt源码(碰到问题的时候,或者文档对函数描述不清楚的时候,可以看一下)
是否应该学习qt源码 如果你想调用某个函数,但是文档并没有清晰描述这个函数的功能的时候,你就需要去阅读源码,看看Qt究竟是怎么实现的.比如用QNetworkAccessManager发送一个QHttp ...
- 使用swagger作为restful api的doc文档生成
初衷 记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情.也许多点,也许少点.甚至,接口总是需要适应新需求的,修改了,增加了,这份 ...
- nova创建虚拟机源码分析系列之一 restful api
开始学习openstack源码,源码文件多,分支不少.按照学习的方法走通一条线是最好的,而网上推荐的最多的就是nova创建虚机的过程.从这一条线入手,能够贯穿openstack核心服务.写博文仅做学习 ...
- 使用Java生成word文档(附源码)
当我们使用Java生成word文档时,通常首先会想到iText和POI,这是因为我们习惯了使用这两种方法操作Excel,自然而然的也想使用这种生成word文档.但是当我们需要动态生成word时,通常不 ...
- Doxygen自动文档生成工具在Eclipse中的集成及使用举例
你有为软件编写说明文档的苦恼吗?当别人甩给你一个庞大的系统,让你根据里面的代码注释理解后写出一份完整的开发文档,你会怎么办?一个个的看代码 然后耗时N天来写吗?这既是一份苦差事也极其耗时,有没有更好的 ...
- 源码分析 Alibaba sentinel 滑动窗口实现原理(文末附原理图)
要实现限流.熔断等功能,首先要解决的问题是如何实时采集服务(资源)调用信息.例如将某一个接口设置的限流阔值 1W/tps,那首先如何判断当前的 TPS 是多少?Alibaba Sentinel 采用滑 ...
- 最长(大)回文串的查找(字符串中找出最长的回文串)PHP实现
首先还是先解释一下什么是回文串:就是从左到右或者从右到左读,都是同样的字符串.比如:上海自来水来自海上,bob等等. 那么什么又是找出最长回文串呢? 例如:字符串abcdefedcfggggggfc, ...
随机推荐
- Django - ModelForm组件
一.ModelForm组件 这是一个神奇的组件,通过名字我们可以看出来,这个组件的功能就是把model和form组合起来,先来一个简单的例子来看一下这个东西怎么用:比如我们的数据库中有这样一张学生表, ...
- web 开发常见问题--Session 与 Cookie 却别
总结: 1.首先,session与cookie都是保存数据的,存在的原因很大程度上是为了解决HTTP协议的无状态特性 2.都是保存数据,却别在于cookie保存在客户端,由浏览器管理,session保 ...
- 分布式计算hadoop三大组件
设计原则:移动计算,而不是移动数据 计算层:Map/Reduce调度层:YARN数据层:HDFS 这三层之间没有必然的依赖性,只是经常这么搭配,而且都是hadoop那个包里一起安装的,三层都可以独立运 ...
- 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 ...
- go——常量
常量是一个简单值的标识符,在程序运行时,不会被修改的量常量中的数据类型只可以是布尔值.数字型(整数型.浮点型和复数)和字符串.常量的定义格式: const identifier [type] = va ...
- Delphi 正则表达式之TPerlRegEx 类的属性与方法(6): EscapeRegExChars 函数
Delphi 正则表达式之TPerlRegEx 类的属性与方法(6): EscapeRegExChars 函数 // EscapeRegExChars 函数可以自动为特殊字符加转义符号 \ var ...
- 微信小程序组件button
表单组件button:官方文档 Demo Code: var types=['default', 'primary', 'warn']; var pageObject = { data: { defa ...
- Kattis - glitchbot 【DFS】
Kattis - glitchbot [DFS] 题意 有一个机器人 刚开始在(0, 0),然后给出一个目标点,并且会给出一系列指令,但是其中会有一个指令是错误的.我们需要找出那个指令,并且改成正确的 ...
- Matlab 使用的一些常用技巧
主要是编程过程中遇到的一些问题和解决,大多数都是来自于Matlab文档.随时总结: Vectorization 向量化是Matlab作为一种专注数值.矩阵计算的语言,和其他语言的一个差别.这也是Mat ...
- OpenGL核心技术之Gamma校正
笔者介绍:姜雪伟,IT公司技术合伙人,IT高级讲师,CSDN社区专家,特邀编辑,畅销书作者,国家专利发明人;已出版书籍:<手把手教你/2.2次幂.Gamma校正后的暗红色就会成为(0.5,0.0 ...