小编wha*_*iff的帖子

在我的API文档中,我想定义每个API端点所需的安全性.该项目已定义角色和权限,用于确定哪些用户可以访问API.Swagger记录此信息的最佳方式是什么？有关如何显示此详细信息的最佳做法或建议吗？

这是我尝试使用securityDefinitions和角色的自定义变量,但是当我通过swagger2markup或使用swagger-ui运行时,该信息(x-role-names)没有被复制到文档中.

    "securityDefinitions": {
    "baseUserSecurity": {
          "type": "basic",
          "x-role-names": "test"
       }
    }

记录每个端点的角色和权限信息的最佳方法是什么？

我正在试图找出让我的API文档成为事实来源的最佳方法,并使用它来理想地通过集成测试或类似的东西来验证实际的Java REST代码.我们使用合同优先或消费者合同类型的方法,因此我们不希望文档必须从带注释的代码生成,并且每次开发人员进行更改时都要更新.

一种想法是使用Swagger,但我不确定如何最好地将其用于验证API.理想情况下,在构建或集成测试过程中进行验证以查看真实响应(如果可能请求)是否与预期匹配是一件好事.我知道Swagger有很多用途和工具,只是想绕过它.或者,如果有更好的替代方法来使用Java代码.

表示具有消息、总元素、数据和状态等基本字段的通用响应/有效负载对象的最佳方式是什么？其中每个 API 之间的可变性是数据元素。例如，一个 API 可能用于权限，因此数据元素将保存一组权限。但对于另一个 API，它将保存不同的对象类型数组。我的主要目标是重用有效负载对象并定义实际数据的下一个“层”。

我希望能够定义一个通用的数据类型 - 就像具有基本字段的“响应”，但我希望能够进一步定义每个 API 的内容（包含权限或角色或其他内容的数据）。

以下是一些已尝试的 JSON 示例，但未按照我们期望的方式在 Swagger UI 中呈现（即 4 个元素的平面结构，其中数据根据 API 定义）。

实施例1-组成：

    {
    "swagger": "2.0",
    "host": "localhost:8888",
    "info": {
        "version": "0.0.1",
        "title": "API"
    },
    "paths": {
        "/permissions": {
            "get": {
                "description": "Returns all permissions",
                "operationId": "getPermissions",
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "200": {
                        "description": "success",
                        "schema": {
                            "$ref": "#/definitions/permissionResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "response": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string",
                    "description": "A …