Swagger Editor是一款产生在完善RESTful API的时代下,由swagger.io发起的开源项目。它允许开发者使用简洁的语法来编写开放API的文档,帮助你更快地将API的基本信息收集和定义成清晰的API文档。
一、简介与安装
Swagger是一种API文档化设计工具,提供了完全的RESTful API文档化解决方案。而Swagger-ui则是一个针对Swagger的UI工具,提供了一个完全交互式工具样式的API探索器,可以根据RESTful API描述文件所提供的API的基本信息自动生成API文档,支持开发人员进行自助式、自控式的API探索、API测试。
Swagger Editor是Swagger的原型、设计与编辑工具,Swagger Editor提供了一个开放而又智能的编辑器,可以用来创建、编辑、审查、校验、发布Swagger API文档,它完全表达了Swagger API设计的途径和架构。
Swagger Editor可以通过三种方式安装:
1. 源代码安装
git clone https://github.com/swagger-api/swagger-editor.git cd swagger-editor npm install npm run build
2. Docker安装
# 从 Docker Hub 下载镜像 docker pull swaggerapi/swagger-editor # 运行容器 docker run -d -p 8888:8080 swaggerapi/swagger-editor
3. 部署在服务器上
下载最新版本的Swagger Editor,并将它部署到你的服务器上,启动应用程序,这样你的Swagger Editor就可以在服务器上访问了。之后可以通过这个URL进行访问:http://localhost:3333/。
二、Swagger Editor详解
1. 定义API文档信息
在Swagger Editor中定义API文档的第一步就是提供文档的元数据。以下是Swagger文档中必填的元数据:
swagger: "2.0" info: version: 1.0.0 title: Sample API description: This is a sample API documentation
Swagger文档的元数据用于定义API相关信息,例如版本号、标题和介绍等。版本号可用于跟踪API的版本,并防止新的API版本对现有API的兼容性造成不利影响。标题和介绍则用于向用户提供有关API的基本信息。除了必填元数据之外,Swagger API文档还可以包含各种可选属性。
2. 定义API路径与操作
Swagger Editor的下一个步骤是为API定义路径和操作。在Swagger中,每个路径重定向到一个或多个操作。操作是实现API端点的方法之一。以下是一个API路径和操作的定义示例:
paths: /user: get: summary: Retrieve a list of users description: Retrieves a list of users in the system responses: "200": description: A list of users was retrieved successfully schema: type: array items: $ref: "#/definitions/User" tags: - User post: summary: Create a new user description: Creates a new user in the system parameters: - name: user in: body required: true schema: $ref: "#/definitions/NewUser" responses: "200": description: A new user was created successfully schema: $ref: "#/definitions/User" tags: - User
在这个示例中,定义了一个路径,该路径响应对包含用户列表的资源的GET请求,响应对创建新用户的POST请求。对于每个URL,可以指定多个操作,这些操作对于响应不同的HTTP方法。每个操作都有一个可选的标签,这使得在许多要素中对操作进行分类和组织非常方便。
3. 定义API模型
在Swagger中,模型是为API文档定义结构的基础。相应的,Swagger Editor可以通过编写JSON模式来定义API模型。以下是定义数据模型的示例:
definitions: User: type: object properties: id: type: integer format: int64 username: type: string NewUser: type: object properties: username: type: string password: type: string
在这个示例中,定义了两个模型:User和NewUser,分别表示保存有关用户记录的数据和创建新用户的数据。每个模型都有一个类型和属性。类型可以是JavaScript对象或它准备好的基本类型之一,如字符串、数字和Boolean。属性描述了对象中保存的数据。属性可以包括名称、类型、格式、枚举、默认值等
三、额外的用法
1. 在Swagger-UI中显示API文档
Swagger Editor不仅可以用来定义API文档,还可以自动生成API文档在Swagger-UI中进行轻松访问。只需要在Swagger Editor中单击"Generate Server"按钮,即可将API定义转换为HTML格式,在Swagger-UI中展示它们。
2. 与后端集成
Swagger Editor还支持与许多不同的后端Web服务框架集成。它们包括Express、Hapi、Sails等。这些框架中的集成使得使用Swagger Editor定义API变得更加容易,并提供了API测试和交互式文档。
3. 自定义主题
Swagger Editor的UI十分简洁,易于操作。如果你希望对UI进行个性化设置,Swagger Editor也提供一些自定义主题的选项。你可以使用CSS文件对Swagger UI进行专业化定制,包括修改文档的字体、颜色、对比度等。
结语
使用Swagger Editor来定义、编写和审查API文档是一项相对简单且重要的任务。其提供了一个完整的、可定制的工具箱,一些工具甚至还提供了API测试和交互式文档。通过使用Swagger Editor提供的这些资源,开发者们可以更快捷地设计API并文档化API,以便更广泛地推广和使用。