基于swagger的RESTful API开发实践

简介:

前言

RESTful架构,是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,所以正得到越来越多网站的采用。后端通过提供一套标准的RESTful API,让网站,移动端和第三方系统都可以基于API进行数据交互和对接,极大的提高系统的开发效率,也使得前后端分离架构成为可能。
因此,不同的测试,开发团队(前端,移动端,第三方接入者等)都需要围绕API进行开发工作,API的规范和文档对于团队开发,测试变得越来越重要。除了一份标准的文档,我们还希望API能够在线测试使用,从而有更直观的API使用体验,降低API的学习成本。这些对于团队的开发协作都会事半功倍。 
本文将介绍一些API文档和开发测试方面的一些实践,使用typeson,docson,swagger-ui等开源工具,建立一个API的集设计,实现,测试,文档的一体化可视平台,让API的开发和使用更加高效。
AI 代码解读

概述

首先我们会通过一个简单系统的RESTful API的开发,介绍如果利用typeson,docson,swagger-ui等工具辅助API的设计和开发,掌握这些工具的使用,提高API的开发效率,质量。
AI 代码解读

在这个实例的开发中,会涉及到以下规范和工具:

  • Swagger

    *Swagger是一种和语言无关的规范和框架,用于定义服务接口,主要用于描述RESTful的API。它专注于为API创建优秀的文档和客户端库。支持Swagger的API可以为API方法生成交互式的文档,让用户可以通过以可视化的方式试验,查看请求和响应、头文件和返回代码,从而发现API的功能。它本身就非常强大,但是Swagger框架还支持为多种流行的语言——包括JavaScript、Python、Ruby、Java、Scala等等——生成客户端代码。*
    *网址: https://helloreverb.com/developers/swagger*
    
    AI 代码解读
  • Swagger-UI

    *为基于Swagger规范的API生成基于基于纯粹HTML,javascript,css的在线可视化文档,同时也能成为API的在线测试工具。*
    *网址: https://github.com/wordnik/swagger-ui*
    AI 代码解读
  • JSON Schema

    *类似于XSD对比与XML的关系,JSON schema是用来描述JSON数据类型的schema。*
    *网址:http://json-schema.org/*
    AI 代码解读
  • DOCSON

    *一个json数据的文档化工具,通过json schema生成对应的在线JSON可视化文档。*
    *网址:https://github.com/lbovet/docson*
    AI 代码解读
  • TypeScript

    *TypeScript是一种由微软开发的自由和开源的编程语言。它是JavaScript的一个超集,而且本质上向这个语言添加了可选的静态类型和基于类的面向对象编程。*
    *网址:http://www.typescriptlang.org/*
    AI 代码解读
  • Typeson

    *利用typescript这种面向对象的javascipt超集,生成json schema。*
    *网址:https://github.com/lbovet/typson*
    
    AI 代码解读

在这个API的开发实践中,我们会贯彻两个理念:

  1. Design-First 设计先行
  2. TDD 测试驱动

从一个基本应用开始

 这部分我们假设开发团队接到一个新的开发需求,开发一个客户邮件营销系统,注册用户可以管理自己的客户,并通过邮件对客户进行营销活动。所有的后台功能通过RESTful API形式提供服务,网站开发,移动端开发,和后端同时进行开发。
首先团队之间需要沟通协调设计API接口设计,形成规范和文档。这就是我们常说的设计先行理念。
AI 代码解读

数据模型设计

可以看到如下页面:
A1

说明docson已经准备好了

  • 第二步,根据业务需要设计json schema:

    1. 我们可以直接手写json schema,入将以下文件保存为/examples/user.json:
"$schema":"http://json-schema.org/draft-04/schema#",
    "title":"User",
    "description":"用户schema",
    "type":"object",
    "properties":{
        "id":{
            "description":"id",
            "type":"number"
        },
        "username":{
            "description":"用户名",
            "type":"string"
        },
        "password":{
            "description":"密码",
            "type":"string"
        },
        "fullname":{
            "description":"全名",
            "type":"string"
        },
        "telphone":{
            "description":"电话号码",
            "type":"string"
        },
        "email":{
            "description":"Email",
            "type":"string"
        },
        "company":{
            "description":"公司名",
            "$ref":"#/definitions/Company"
        },
        "customers":{
            "description":"客户",
            "type":"array",
            "items":{
                "$ref":"#/definitions/Customer"
            },
            "minItems":1,
            "uniqueItems":true
        },
        "mailTemplates":{
            "description":"模板",
            "type":"array",
AI 代码解读

将对应的地址http://localhost:8080/docson/examples/user.json 输入docson,回车后将看到图形化的schema:
A2

点击Customer等按钮可以查看对应的跟详细的数据类型信息:
A3

这样所有人员都可以直接查看数据模型的定义,协同设计。

  1. 除了手写外,我们也可以利用Typescript/typeson来辅助我们生成json schema
    具体可以参考网站和demo:http://lbovet.github.io/typson-demo/ 需要稍微熟悉下typescript

A4

API接口的设计

在数据模型定义好后,我们接着可以定义具体需要的API列表和每个API的接口形式,请求方法,输入输出参数等具体信息。在此我们利用前面设计好的json schema,结合swagger-ui工具,就可以定义设计API列表。
AI 代码解读
  • 第一步 准备好swagger-ui,部署并启动。参考网址: https://github.com/wordnik/swagger-ui
    这里我们将用swagger-ui的离线版本,先行设计API。
  • 第二步 设计每个API,按功能组织分类, 将设计好的json schema引入,同时设计如下API
"apis":[
        {
            "path":"/accounts/",
            "operations":[
                {
                    "parameters":[
                        {
                            "name":"account",
                            "description":"Create a new account",
                            "required":true,
                            "dataType":"Account",
                            "paramType":"body"
                        }
                    ],
                    "responseMessages":[
                        {
                            "code":401,
                            "message":"Unauthorized"
                        },
                        {
                            "code":500,
                            "message":"Internal Application Error"
                        }
                    ],
                    "httpMethod":"POST",
                    "notes":null,
                    "responseClass":"Account",
                    "nickname":"createAccount",
                    "summary":"Create a new account",
                    "produces":[
                        "application/json"
                    ]
                }
            ]
        },
AI 代码解读

完成后,我们将可以得到如下的API在线文档:
A5

如某个具体AP,获取账户的具体信息
A6

如果API已经准备好,或者后端提供了一个mock实现,那么直接点击“try it out”,就可以直接调用该API,输入测试数据,测试返回数据和错误信息。

同时根据数据模型的json schema,swagger-ui 会自动生成对应json数据的form表单,无论结构多复杂,这极大方便API使用者对API的上手和测试。
A7

API的开发测试

到目前阶段,我们可以看到,及时API完全没有编码实现,我们也有一个很清晰的API文档和测试环境。各个开发测试团队可以在这个在线文档和测试平台上,协同各自开发测试。比如:
AI 代码解读
  • API开发团队根据这个文档,开发实现具体的API功能
  • 前端团队或者移动端,根据这个API文档,分别独自开发各自功能,mock API的实现。
  • 测试团队可以直接根据这个API的测试平台,利用selenium工具录制测试脚本和准备测试数据,在开发团队实现前就可以把测试准备好,用测试驱动开发

API使用阶段

 在API开发测试完成后,需要提供API给外部系统使用,我们可以直接把这个swagger-ui建立的在线文档和测试平台提供给开发使用者,作为标准的文档和测试工具。这样也不需要格外写一份静态的接口文档给用户,我们提供的是一份标准的live文档和测试工具,可以极大的方便使用着了解API,减低使用者的学习成本。
AI 代码解读

总结

本文只是简单的介绍了RESTful API开发中利用一些工具进行辅助开发,希望docson,typeson,swagger-ui 等纯粹的基于html,javascript的前端工具能够方便大家的API开发,建立一个API的在线文档和测试中心。这对于需要提供API服务给第三方的平台开发者具有较大的价值。关于更多相关规范和工具的使用,希望大家参考对应网站提供的文档,深入掌握,也何以和作者交流
AI 代码解读
目录
打赏
0
3
2
2
192
分享
相关文章
RESTful与GraphQL:电商API接口设计的技术细节与适用场景
本文对比了RESTful与GraphQL这两种主流电商API接口设计方案。RESTful通过资源与HTTP方法定义操作,简单直观但可能引发过度或欠获取数据问题;GraphQL允许客户端精确指定所需字段,提高灵活性和传输效率,但面临深度查询攻击等安全挑战。从性能、灵活性、安全性及适用场景多维度分析,RESTful适合资源导向场景,GraphQL则适用于复杂数据需求。实际开发中需根据业务特点选择合适方案,或结合两者优势,以优化用户体验与系统性能。
京东拍立淘图片搜索 API 接入实践:从图像识别到商品匹配的技术实现
京东拍立淘图片搜索 API 是基于先进图像识别技术的购物搜索接口,支持通过上传图片、URL 或拍摄实物搜索相似商品。它利用机器学习和大数据分析,精准匹配商品特征,提供高效、便捷的搜索体验。接口覆盖京东海量商品资源,不仅支持外观、颜色等多维度比对,还结合用户行为数据实现智能推荐。请求参数包括图片 URL 或 Base64 编码,返回 JSON 格式的商品信息,如 ID、价格、链接等,助力消费者快速找到心仪商品,满足个性化需求。
170 18
Go语言网络编程:使用 net/http 构建 RESTful API
本章介绍如何使用 Go 语言的 `net/http` 标准库构建 RESTful API。内容涵盖 RESTful API 的基本概念及规范,包括 GET、POST、PUT 和 DELETE 方法的实现。通过定义用户数据结构和模拟数据库,逐步实现获取用户列表、创建用户、更新用户、删除用户的 HTTP 路由处理函数。同时提供辅助函数用于路径参数解析,并展示如何设置路由器启动服务。最后通过 curl 或 Postman 测试接口功能。章节总结了路由分发、JSON 编解码、方法区分、并发安全管理和路径参数解析等关键点,为更复杂需求推荐第三方框架如 Gin、Echo 和 Chi。
RESTful接口设计与测试实践
通过理解和实践上述原则和步骤,你就可以设计和测试你的RESTful接口了。最后,它可能会变成你为优化系统性能和用户体验所使用的重要工具,因为好的接口设计可以使得从服务器端到客户端的通信更加直接和有效,同时提升产品的使用体验和满意度。如此一来,写一个好的RESTful接口就变成一种享受。
121 18
京东拍立淘图片搜索 API 接口使用指南:从原理到实践
京东拍立淘图片搜索API,基于先进图像识别技术,支持上传图片、URL或拍摄实物搜索相似商品。其特点包括:搜索便捷高效,用户可快速发起搜索;精准匹配结果,通过算法捕捉商品特征确保准确;数据覆盖广泛,依托京东海量商品资源满足个性化需求;智能推荐拓展,根据用户行为挖掘潜在需求,提升购物体验。
利用 RunnerGo 深度探索 API 性能测试:从理论到实践
API性能测试是保障应用稳定性和用户体验的关键环节。本文详细探讨了如何使用RunnerGo全栈测试平台进行高效API性能测试,涵盖测试计划创建、场景设计、参数配置到执行与分析全过程。通过电商平台促销活动案例,展示了高并发下的测试策略与优化措施,如代码与数据库查询优化、数据库连接池扩容、服务器资源配置调整及缓存策略实施等。最终显著提升系统性能,满足高并发需求。API性能测试需持续关注与优化,以适应业务发展和用户需求变化。
135 33
基于 API 网关践行 API First 开发实践
API First 开发模式的核心在于:以 API 为先,将其视为“头等公民”,在构建应用、服务及集成之前,应优先定义并设计 API 及其配套。API First 作为一种相对较新的开发模式,它已逐渐流行并获得业内的广泛认可。
319 115
如何从 Swagger 导出 API 文档
Swagger 使这项任务相对简单,允许开发者以各种格式(如 JSON 和 YAML)导出 API 文档。在这篇博文中,我们将详细探讨如何从 Swagger 导出 API 文档。
如何从 Swagger 导出 API 文档
构建智能天气助手:基于大模型API与工具函数的调用实践
在人工智能快速发展的今天,大语言模型(LLM)已经成为构建智能应用的重要基础设施。本文将介绍如何利用大模型API和工具函数集成,构建一个能够理解自然语言并提供精准天气信息的智能助手。
382 11
Understanding RESTful API and Web Services: Key Differences and Use Cases
在现代软件开发中,RESTful API和Web服务均用于实现系统间通信,但各有特点。RESTful API遵循REST原则,主要使用HTTP/HTTPS协议,数据格式多为JSON或XML,适用于无状态通信;而Web服务包括SOAP和REST,常用于基于网络的API,采用标准化方法如WSDL或OpenAPI。理解两者区别有助于选择适合应用需求的解决方案,构建高效、可扩展的应用程序。

热门文章

最新文章

AI助理

你好,我是AI助理

可以解答问题、推荐解决方案等

登录插画

登录以查看您的控制台资源

管理云资源
状态一览
快捷访问