.net Core & Swashbuckle/Swagger：如何提供原始 json 示例？

Question

我有一个 WebAPI 控制器，其操作 returning JSON 模式。这个JSON return值是不能序列化创建的，所以我设计了如下操作方法：

    [HttpGet("{serviceName}/contract")]
    [SwaggerResponse((int)HttpStatusCode.OK, Type = typeof(object))]
    public IActionResult GetContract(string serviceName)
    {
        return Content("{ \"type\": \"object\" }", "application/json"); // for example ...
    }

现在我想为 Swagger 提供一个或一些已记录的 return 值。但我无法做到这一点。有 SwaggerRequestExample 属性，但如前所述，这需要 return 类型，在我的情况下不适用。

基本上我在寻找类似的方法（只是动态的）：

[SwaggerResponseExample((int)HttpStatusCode.OK, "{\"anyJson\": \"Yes, I am!\"}")]

当然，这样更好：

[SwaggerResponseExample((int)HttpStatusCode.OK, RawJsonFabricType="TypeName", RawJsonStaticMethod="MethodName")]

用例：我需要在操作方法中 return 的 JSON 模式存储在数据库中，而不是在程序代码本身中创建。

这种 JSON 架构值的具体示例是：

{
  "$id": "https://example.com/person.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Person",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "The person's first name."
    },
    "lastName": {
      "type": "string",
      "description": "The person's last name."
    },
    "age": {
      "description": "Age in years which must be equal to or greater than zero.",
      "type": "integer",
      "minimum": 0
    }
  }
}

非常感谢您的帮助。谢谢！

我正在使用 c#.net core 6。

Answer 1

经过一番尝试，我找到了解决方案：

首先：添加ExampleProvider并使用泛型类型JsonDocument（来自System.Text.Json）：

    public class ServiceDemandContractExampleProvider : IExamplesProvider<JsonDocument>
    {
        /// <inheritdoc/>
        public JsonDocument GetExamples()
        {
            var jsonToShow = JsonDocument.Parse(@"{
  ""$id"": ""https://example.com/person.schema.json"",
  ""$schema"": ""https://json-schema.org/draft/2020-12/schema"",
  ""title"": ""Person"",
  ""type"": ""object"",
  ""properties"": {
                ""firstName"": {
                    ""type"": ""string"",
      ""description"": ""The person's first name.""
                },
    ""lastName"": {
                    ""type"": ""string"",
      ""description"": ""The person's last name.""
    },
    ""age"": {
                    ""description"": ""Age in years which must be equal to or greater than zero."",
      ""type"": ""integer"",
      ""minimum"": 0
    }
            }
        }");

            return jsonToShow;
        }
    }

到 JsonDocument.Parse 放任何东西 JSON （在我的例子中是从数据库加载的内容）。

然后在操作方法中添加如下属性：

[SwaggerResponse((int)HttpStatusCode.OK, Type = typeof(object))]
[SwaggerResponseExample((int)HttpStatusCode.OK, typeof(ServiceDemandContractExampleProvider))]

它有效：

.net Core & Swashbuckle/Swagger：如何提供原始 json 示例？

.net Core & Swashbuckle/Swagger: How to provide raw json example?

c#

.net-core

swagger

webapi