向 Swagger UI 添加实现注释和描述答案

【问题标题】：Adding Implementation Notes and Description to Swagger UI向 Swagger UI 添加实现注释和描述
【发布时间】：2016-10-27 15:58:07
【问题描述】：

我正在尝试将 Implementation Notes 和 Description 添加到我的 Swagger UI。但是，如下实现时，两者都不会显示在 UI 上：

{
"swagger" : "2.0",
"info" : {
    "description" : "The definition of the Rest API to service plugin over https on port 9443.",
    "version" : "1.0",
    "title" : "Plugin Rest API",
    "contact" : {
       "name" : "John Doe",
      "email" : "john.doe@gmail.com"
    }
},
"basePath" : "/service",
"tags" : [ {
    "name" : "service"
  } ],
"schemes" : [ "https" ],
"paths" : {
"/entry" : {
   "get" : {
       "notes" : "This is a note",
       "method" : "get",
       "tags" : [ "service" ],
       "summary" : "Get an entry by first name and last name",
       "description" : "This is a description",
       "operationId" : "getEntry",
       "produces" : [ "application/xml", "application/json" ],
       "parameters" : [ {
           "name" : "first",
           "in" : "query",
           "description" : "The first name",
           "required" : true,
           "type" : "string"
        }, {
      "name" : "last",
      "in" : "query",
      "description" : "The last name",
      "required" : true,
      "type" : "string"
    } ],
    "responses" : {
      "200" : {
        "description" : "Matching entry, or entries, if any, were returned",
        "schema" : {
          "$ref" : "#/definitions/Service"
        }
      }
    }   
  },

我不确定我在代码中做错了什么。我已经在各种示例 swagger.json 文件上对其进行了测试，但我似乎无法让它工作。

【问题讨论】：

哪些字段没有出现？摘要、描述等？
描述和注释@fehguy

标签： swagger swagger-ui swagger-2.0

【解决方案1】：

notes 不是一个招摇的领域。见documentation

您的 description 字段被写入了两次，因此第一个已被覆盖。

【讨论】：

【解决方案2】：

您可以在@ApiOperation注解中使用notes标签添加实现注释，如下所示，

@ApiOperation(notes = "Your Implementation Notes will show here[![enter image description here][1]][1]", value = "Add Customer Payment Details and Generate Payment Link through Batch.", nickname = "insertPaymentBatch",  tags = 
            "Insert Payment" )

【讨论】：