向Swagger UI添加实现说明和描述

Question

我正在尝试将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文件上测试了它，我似乎无法让它工作。

Answer 1

备注不是一个招摇的领域。请参阅documentation

您的说明字段会被写入两次，因此第一个字段已被覆盖。

Answer 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" )