README

此存储库包含了一些OAS/Swagger API文档的示例，以及创建良好API文档和使用它构建模拟服务器的指南。

为什么要使用API文档？

当两个不同的团队分别开发后端和前端时 - 他们都需要一份说明请求和响应数据格式的文档。当然，他们会在Slack等平台上进行协商并试图记住它。然而，这样你的产品就变成了一个“黑盒子”，这给支持带来了极大的困难。

作为解决方案，我们建议创建一个结构化的API文档，它不依赖于某些特定的技术。我的意思是，你不需要学习PHP或JavaScript来创建这样的文档。如今，有两种流行的格式：OAS（开放API规范）和RAML（RESTful API建模语言）。RAML非常酷，但OAS有更大的社区，因此我们选择了OAS。不幸的是，我们需要使用过时的OAS2格式（也称为“Swagger”），因为OAS3不受众多工具的支持，你可能会在未来需要它。

内容

您可以在本存储库中找到以下内容

Swagger API文档的示例（OAS2、OAS3），以Yaml格式。这是一个多文档结构，具有跨文档引用，以保持DRY（不要重复自己）
Swagger UI API文档查看器
PHP工具，用于将多个文档yaml合并为一个文档。遗憾的是，现有的工具只能处理单个文档。
PHP工具，用于使用Faker库生成伪造对象示例。

编写文档

设置项目

首先，您可以克隆此存储库到某个Web服务器。它使用静态HTML和JavaScript，因此您不需要任何特殊的服务器配置。您需要在服务器上安装Composer包管理器。

git clone https://github.com/justcoded/swagger-tools.git /path/to/docroot/swagger
cd /path/to/docroot/swagger
composer install

这就完了，您可以在浏览器中打开http://mydomain.com/swagger/，您将获得带有我们示例文档的Swagger UI。

或者您可以尝试使用Docker运行nginx中的swagger UI，如下所示

docker run -p 8080:80 --name swagger-tools -v ./:/usr/share/nginx/html:ro nginx

创建您的文档

现在让我们转到examples文件夹。您可以从复制一些文件夹开始。之后，您需要更新index.html以指向您的新文档。

<script>
window.onload = function() {

  // Build a system
  const ui = SwaggerUIBundle({
	url: "./examples/jsonapi/swagger.yaml",
	...

如前所述，我们使用OAS2格式，规范可以在这里找到

如果您对swagger格式不熟悉，您需要学习以下声明

定义对象（用于模型和对象）
路径对象 - 用于路由
参数对象 - 用于定义参数
响应对象 - 用于响应

我们建议使用的文档结构

- routes/			# Routes/Paths definitions grouped by section
	- auth.yaml
	- users.yaml

- models.yaml			# Models/Requests definition
- params.yaml			# Params, which are similar for paths in different routes groups
- responses.yaml 		# General responses definitions like 204, 401, 403, 404, 422, 500, etc.
- swagger.yaml 			# Main file, which includes other files

由于OAS2格式的限制，我们需要在主文件中列出所有路由

paths:
  /auth/sign-in:
    $ref: "routes/auth.yaml#/paths/login"
  /auth/verify:
    $ref: "routes/auth.yaml#/paths/verify"
  /auth/password-reset:
    $ref: "routes/auth.yaml#/paths/resetPassword"
  ...

有了这些示例，我想其他事情都是不言自明的。

Swagger编辑器

我们推荐使用 WebStorm 或 PHPStorm（或任何其他 JetBrains IDE）来编辑 Swagger YAML 文件。为了在 Swagger 标识符和引用上实现自动完成，您需要安装名为 Swagger 插件的插件。

JSON 格式

当您开发 API 时，确定 JSON 应该是什么样子的格式总是一个难题。为了解决这个问题，我们建议遵循 JSONAPI 规范：https://jsonapi.fullstack.org.cn/

总的来说，它定义了我们需要以如下格式传输数据

{
	"data": [{ // collection or resource itself
		"type": 'resource type',
		"id": 'some id',
		"attributes": {
			// resource attribute
		},
		"relationships": {
			'relation name': {
				"data": { "type": "resource type", "id": "some id" }
			}
			// ...
		}
	}],
	"included": [{ // data for related resources
        "type": "related resource type",
        "id": "some id",
        "attributes": {
        	// related resource data
        }
        // ...
    }],
	"meta": {
		// some other data like pagination info, tokens, etc.
	}
}

这种格式非常适合 JavaScript 库，如 React.js、Vue.js 和 Angular，因为它可以根据资源类型轻松填充作用域。

JSONAPI 有许多现成的实现：https://jsonapi.fullstack.org.cn/implementations/

非资源请求的 JSONAPI 格式

不幸的是，这个规范没有回答如何形成非资源请求。通常这些是一些操作，例如“搜索”。

我们建议定义我们可以传输一个类型为“userInput”的文档类型模型，它可以从路由到路由变化。看起来像这样

{
	"data": {
		"type": "userInput",
		"attributes": {
			// key/value pairs of user input data
		}
	}
}

PHP 工具

合并多文档 Swagger YAML 文档
为模拟服务器生成枚举的伪数据

合并工具

./cli/swagger-merge.php examples/v2.0/swagger.yaml > merged-swagger2.yaml

Faker 工具

将 x-faker 属性添加到您的属性中

swagger: '2.0'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
        minimum: 1
      email:
        type: string
        format: email
        x-faker: email
      first_name:
        type: string
        x-faker: firstName
      last_name:
        type: string
        x-faker: lastName

运行命令

./cli/swagger-faker.php examples/merged/swagger2.yaml -n10 -r -c > swagger-faked.yaml

您将得到

definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
        minimum: 1
      email:
        type: string
        format: email
        x-faker: email
        enum:
          - muhammad.schuster@yahoo.com
          - hansen.rudy@nolan.com
          - nlittel@hotmail.com
          - gleason.araceli@witting.com
          - sreichert@hotmail.com
          - swift.dayna@kris.com
          - russel55@gmail.com
          - dicki.emery@hotmail.com
          - morris77@hotmail.com
          - lprice@yahoo.com
      first_name:
        type: string
        x-faker: firstName
        enum:
          - Denis
          - Donna
          - Elissa
          - Brandyn
          - Dino
          - Linda
          - Sadye
          - Kenneth
          - Michel
          - Theo

	  ...

    required:
  	- id
  	- email
  	- first_name
  	- last_name
  	- profile

使用此存储库作为依赖项

当然，您可以将此存储库作为依赖项添加到您的项目中，将 Swagger UI 资产符号链接到您的公共存储库，并在您的框架内部创建模板以打印 Swagger UI 界面，指向某些生成的文档。

例如，我们创建了 Yii 扩展，包装了我们的 PHP 工具：https://github.com/justcoded/yii2-swaggerviewer

justcoded / swagger-tools

维护者

详细信息