开发者社区> 桃子红了呐> 正文

使用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,如需转载请自行联系原作者

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
盘点操作URL中常用的几个高效API
通常在实际项目中,无论操作数据、或是dom,我们需要熟悉一些浏览器的API,或是js原生给我们扩展的API,我们熟悉了这些API,某种意义上来说,一些高效的API和方法常常会解惑你项目中遇到的很多疑难杂症。
36 0
使用 Schematics 创建的 Spartacus Storefront,在 index.html 里指定 OCC API url
使用 Schematics 创建的 Spartacus Storefront,在 index.html 里指定 OCC API url
21 0
关于SAP Commerce Cloud OCC API url里不包含user信息的问题
关于SAP Commerce Cloud OCC API url里不包含user信息的问题
60 0
【视觉智能开放平台】关于调用API上传图片url地址等相关问题
阿里云视觉智能开放平台(https://vision.aliyun.com/)目前已上线超过70种视觉AI能力,并通过API的形式提供给用户接入,用户在本地调用API接口时需要上传图片url地址进行识别,但本地调用和线上调式不同,经常会出现url错误的问题。今天就和大家说说这些错误的对应解决方案有哪些。
832 0
SharePoint REST API - 确定REST端点URL
博客地址:http://blog.csdn.net/FoxDave SharePoint REST端点URI的结构 在你能够通过REST访问SharePoint资源之前,首先你要做的就是找出对应的URI端点,如果你对Client API熟悉,有些时候也可以参考Client API去猜测构建,例如。
1179 0
ASP.NET Core Web API 帮助页
ASP.NET Core Web API 帮助页
78 0
文章
问答
文章排行榜
最热
最新
相关电子书
更多
CUDA Math API
立即下载
阿里云 API 精选手册(Alibaba Cloud API Playbook)
立即下载
重保场景及API安全指南
立即下载