Sn0rt opened a new issue, #8767: URL: https://github.com/apache/apisix/issues/8767
### Description # OAS-Validation detail ## 描述 Validate HTTP requests and responses against API specifications. Supports Swagger v2 and OpenAPI v3 specification JSON request and response bodies, and supports schema definitions described using JSON Schema draft v4. 属性 | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | --- | --- | --- | --- | --- | --- | | api_spec | string | 是 | empty | swagger body | 使用 Swagger 或 OpenAPI 定义的 API 规范。 这可以是基于 JSON 或 YAML 的文件。 如果使用 YAML 文件，规范需要进行 URL 编码以保留 YAML 格式。 | | verbose_response | boolean | 是 | true | true/false | 如果设置为 true，则返回无效请求和响应的详细错误消息。 这在测试时很有用。 | 和 request-validation 的区别 1. 使用 swagger 描述 api 的字段格式, 可以对一组接口进行描述验证. 2. ## 启用插件 以下示例展示了如何在指定路由上启用 `oas-validation` 插件，并设置 api_spec 字段 和 verbose_response ```json curl http://127.0.0.1:9180/apisix/admin/routes/5 \ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' { "uri": "/", "plugins": { "oas-validation": { "api_spec": "json swaggger body", "verbose_response": true } }, "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:8080": 1 } } } ' ``` ## Example 1. 创建 upstream ```json curl "http://127.0.0.1:9180/apisix/admin/upstreams/1"; \ -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d ' { "type": "roundrobin", "nodes": { "httpbin.org:80": 1 } }' {"key":"\/apisix\/upstreams\/1","value":{"id":"1","nodes":{"httpbin.org:80":1},"create_time":1675229644,"update_time":1675229644,"hash_on":"vars","scheme":"http","type":"roundrobin","pass_host":"pass"}} ``` 1. 创建并查询 route ```bash curl "http://127.0.0.1:9180/apisix/admin/routes/1"; \ -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d ' { "methods": ["POST"], "host": "example.com", "uri": "/anything/*", "upstream_id": "1" }' curl -X GET "http://127.0.0.1:9180/apisix/admin/routes/1"; -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" {"key":"\/apisix\/routes\/1","value":{"id":"1","create_time":1675231122,"status":1,"upstream_id":"1","methods":["POST"],"update_time":1675231820,"host":"example.com","uri":"\/anything\/*","priority":0},"createdIndex":17,"modifiedIndex":20} ``` 1. 测试一下 route ```bash curl -i -X POST "http://127.0.0.1:9080/anything/POST"; -H "Host: example.com" -d '{"name": "2102312JSWCNJB000312"}' -H 'accept: application/json' -H 'Content-Type: application/json' HTTP/1.1 200 OK Content-Type: application/json Content-Length: 554 Connection: keep-alive Date: Wed, 01 Feb 2023 06:50:41 GMT Access-Control-Allow-Origin: * Access-Control-Allow-Credentials: true Server: APISIX/3.1.0 { "args": {}, "data": "{\"name\": \"2102312JSWCNJB000312\"}", "files": {}, "form": {}, "headers": { "Accept": "application/json", "Content-Length": "32", "Content-Type": "application/json", "Host": "example.com", "User-Agent": "curl/7.85.0", "X-Amzn-Trace-Id": "Root=1-63da0bc1-6494eb36237cca65385c33f8", "X-Forwarded-Host": "example.com" }, "json": { "name": "2102312JSWCNJB000312" }, "method": "POST", "origin": "172.19.0.1, 143.92.118.2", "url": "http://example.com/anything/POST"; } ``` 1. Update the route to use swagger's validate ```bash { "uri": "/get", "plugins": { "oas-validation": { "api_sepc": { "swagger": "2.0", "info": { "version": "1.0.6", "title": "example api" }, "host": "httpbin.org", "basePath": "/v2", "schemes": [ "http" ], "paths": { "/post": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "body", "required": true, "schema": { "$ref": "#/definitions/User" } } ], "responses": { "200": { "description": "Create user successfully" }, "405": { "description": "Invalid input" } } } } }, "definitions": { "User": { "type": "object", "properties": { "name": { "type": "string", "example": "doggie" } } } } }, "verbose_response": true } } } ``` ## 测试插件(TODO After enabling the plugin as configured above, use the `curl` command to request the route: Verify that swagger validates the body, the expected behavior is to provide an error of incorrect format. ```json curl -i -X POST "http://127.0.0.1:9080/anything/POST"; -H "Host: example.com" -d '{"name": false}' -H 'accept: application/json' -H 'Content-Type: application/json' ``` PASS ```bash curl -i -X POST "http://127.0.0.1:9080/anything/POST"; -H "Host: example.com" -d '{"name": "2102312JSWCNJB000312"}' -H 'accept: application/json' -H 'Content-Type: application/json' ``` ## disbale plugin When you need to disable the plugin, you can delete the corresponding JSON configuration with the following command, and APISIX will automatically reload the relevant configuration without restarting the service: ```json curl "http://127.0.0.1:9180/apisix/admin/routes/1"; \ -H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d ' { "methods": ["POST"], "host": "example.com", "uri": "/anything/*", "upstream_id": "1" }' ```% -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
