使用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:  - 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













本文转自张昺华-sky博客园博客,原文链接:http://www.cnblogs.com/bonelee/p/6297048.html,如需转载请自行联系原作者
相关文章
|
7天前
|
网络协议 JavaScript 安全
第十一篇 前沿趋势与展望:深入探索GraphQL、RESTful API、WebSocket、SSE及QUIC与HTTP/3
第十一篇 前沿趋势与展望:深入探索GraphQL、RESTful API、WebSocket、SSE及QUIC与HTTP/3
|
2天前
|
JSON 测试技术 API
pyhttptest 与 RESTful API 测试的完全指南
现在,无论是开发还是使用服务,我们每个人都面临着 REST API 的挑战。同时,我们正处于微服务的流行时代,我们将业务逻辑拆分为多个独立的小服务。这些服务大多遵循 RESTful 原则,并使用 JSON 格式进行通信,因为其简单性使其成为最广泛使用的格式。
|
2天前
|
缓存 测试技术 API
构建高效可扩展的RESTful API:后端开发的实践指南
【5月更文挑战第21天】 在现代Web开发领域,构建一个高效、可扩展且易于维护的RESTful API是至关重要的任务。本文将深入探讨如何利用最佳实践和先进技术栈来设计和实现一个健壮的后端服务。我们将讨论API设计原则、数据库优化策略、缓存机制、负载均衡以及容器化部署等方面,旨在为后端开发者提供一套全面的指导方案。
|
3天前
|
缓存 API 数据库
构建高效Python Web应用:Flask框架与RESTful API设计原则
【5月更文挑战第20天】 在现代Web开发中,构建一个轻量级且高效的后端服务至关重要。本文将深入探讨如何使用Python的Flask框架结合RESTful API设计原则来创建可扩展和易于维护的Web应用程序。我们将通过分析Flask的核心特性,以及如何利用它来实现资源的合理划分、接口的版本控制和请求处理优化等,来指导读者打造高性能的API服务。文中不仅提供了理论指导,还包括了实践案例,旨在帮助开发者提升开发效率,并增强应用的稳定性和用户体验。
|
3天前
|
Web App开发 存储 开发框架
使用Node.js构建RESTful API
【5月更文挑战第20天】本文指导使用Node.js和Express构建RESTful API。首先确保安装了Node.js,然后初始化项目,安装Express框架。在`app.js`中创建API,定义GET路由`/api/users`返回用户列表。运行服务器并测试API,最后讨论如何扩展API和提升其功能。这是一个构建RESTful API的基础入门教程。
|
Java API
Java:一个API文档框架Swagger
Java:一个API文档框架Swagger
104 0
Java:一个API文档框架Swagger
|
6天前
|
监控 安全 数据挖掘
Email 接口API有哪些?具体分析一下阿里云和AOK的优点
本文介绍了常见的Email接口API,如阿里云邮件推送、AOKSend、SendGrid、Mailgun和Amazon SES。阿里云API以其高稳定性和数据分析功能脱颖而出,支持批量发送和多语言;而AOKSend API以易于集成、高安全性和优秀客户支持为亮点。企业在选择时应考虑自身需求和预算,以优化邮件营销效果。
|
6天前
|
定位技术 API
Angular 调用导入百度地图API接口,2024春招BAT面试真题详解
Angular 调用导入百度地图API接口,2024春招BAT面试真题详解
|
7天前
|
JSON 安全 API
解锁淘宝商品评论API接口:电商数据分析的新视角
淘宝商品评论API接口是淘宝开放平台提供的一组API接口,允许开发者通过编程方式获取淘宝商品评论数据。这些接口可以获取到商品的详细信息、用户评论、评分等数据,为电商数据分析提供了丰富的素材。
|
7天前
|
缓存 负载均衡 安全
探索API接口开发(定制与开发接口)
在当今数字化、互联互通的时代,API(应用程序编程接口)已经成为连接不同软件、服务和应用的关键桥梁。API接口开发,作为软件架构和系统设计的重要组成部分,不仅影响着数据交换的效率,更决定了整个系统的灵活性和可扩展性。本文将深入探讨API接口开发的各个方面,包括其重要性、开发流程、最佳实践以及面临的挑战。