将HTML加载到Swagger文档中执行说明

Question

我试图使用Swagger Docs为给定端点的我的实现说明显示HTML。下面，我将HTML输入为字符串，但我喜欢将它们作为某种模块加载，以便我可以单独编辑HTML文件。

我在Google Group找不到答案，我想看看在创建某种grunt插件来处理它之前是否已经解决了这个问题。

这里是我当前的代码：

module.exports = function (swagger) { 

var docs = swagger.createResource("/docs/endpoint"); 

docs.get('/endpoint', "Endpoint Title", { 
    "summary": "Some description about the endpoint", 
    "notes": "               \ 
     <h2>Getting Started with Endpoint:</h2>       \ 
     <br /><p>This endpoint some some really important things.</p>  \ 
    ", 
    "type": "", 
    "nickname": "", 
    "parameters": [ 
    { 
     "name": "apiKey", 
     "description": "The API Key for the requesting application", 
     "required": true, 
     "type": "string", 
     "paramType":"query" 
    }] 
[...] 

有没有实现这一个更清洁的方式？

Answer 1

Swagger 2.0为丰富的文档增加了更多的灵活性。

其中一种方法是在description字段中添加降价标签（GFM flavor）。

另一种方法是在适用的情况下使用externalDocs属性添加外部文档资源。一个例子是：

{ 
    "swagger": "2.0", 
    "info": { 
    "version": "1.0.0", 
    "title": "Swagger Petstore", 
    "description": "A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specification", 
    "termsOfService": "http://helloreverb.com/terms/", 
    "contact": { 
     "name": "Wordnik API Team", 
     "email": "foo@example.com", 
     "url": "http://madskristensen.net" 
    }, 
    "license": { 
     "name": "MIT", 
     "url": "http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT" 
    } 
    }, 
    "externalDocs": { 
    "description": "find more info here", 
    "url": "https://helloreverb.com/about" 
    }, 
    "host": "petstore.swagger.wordnik.com", 
    "basePath": "/api", 
    "schemes": [ 
    "http" 
    ], 
    "consumes": [ 
    "application/json" 
    ], 
    "produces": [ 
    "application/json" 
    ], 
    "paths": { 
    "/pets": { 
     "get": { 
     "description": "Returns all pets from the system that the user has access to", 
     "operationId": "findPets", 
     "externalDocs": { 
      "description": "find more info here", 
      "url": "https://helloreverb.com/about" 
     }, 
     "produces": [ 
      "application/json", 
      "application/xml", 
      "text/xml", 
      "text/html" 
     ], 
     "parameters": [ 
      { 
      "name": "tags", 
      "in": "query", 
      "description": "tags to filter by", 
      "required": false, 
      "type": "array", 
      "items": { 
       "type": "string" 
      }, 
      "collectionFormat": "csv" 
      }, 
      { 
      "name": "limit", 
      "in": "query", 
      "description": "maximum number of results to return", 
      "required": false, 
      "type": "integer", 
      "format": "int32" 
      } 
     ], 
     "responses": { 
      "200": { 
      "description": "pet response", 
      "schema": { 
       "type": "array", 
       "items": { 
       "$ref": "#/definitions/pet" 
       } 
      } 
      }, 
      "default": { 
      "description": "unexpected error", 
      "schema": { 
       "$ref": "#/definitions/errorModel" 
      } 
      } 
     } 
     }, 
     "post": { 
     "description": "Creates a new pet in the store. Duplicates are allowed", 
     "operationId": "addPet", 
     "produces": [ 
      "application/json" 
     ], 
     "parameters": [ 
      { 
      "name": "pet", 
      "in": "body", 
      "description": "Pet to add to the store", 
      "required": true, 
      "schema": { 
       "$ref": "#/definitions/newPet" 
      } 
      } 
     ], 
     "responses": { 
      "200": { 
      "description": "pet response", 
      "schema": { 
       "$ref": "#/definitions/pet" 
      } 
      }, 
      "default": { 
      "description": "unexpected error", 
      "schema": { 
       "$ref": "#/definitions/errorModel" 
      } 
      } 
     } 
     } 
    }, 
    "/pets/{id}": { 
     "get": { 
     "description": "Returns a user based on a single ID, if the user does not have access to the pet", 
     "operationId": "findPetById", 
     "produces": [ 
      "application/json", 
      "application/xml", 
      "text/xml", 
      "text/html" 
     ], 
     "parameters": [ 
      { 
      "name": "id", 
      "in": "path", 
      "description": "ID of pet to fetch", 
      "required": true, 
      "type": "integer", 
      "format": "int64" 
      } 
     ], 
     "responses": { 
      "200": { 
      "description": "pet response", 
      "schema": { 
       "$ref": "#/definitions/pet" 
      } 
      }, 
      "default": { 
      "description": "unexpected error", 
      "schema": { 
       "$ref": "#/definitions/errorModel" 
      } 
      } 
     } 
     }, 
     "delete": { 
     "description": "deletes a single pet based on the ID supplied", 
     "operationId": "deletePet", 
     "parameters": [ 
      { 
      "name": "id", 
      "in": "path", 
      "description": "ID of pet to delete", 
      "required": true, 
      "type": "integer", 
      "format": "int64" 
      } 
     ], 
     "responses": { 
      "204": { 
      "description": "pet deleted" 
      }, 
      "default": { 
      "description": "unexpected error", 
      "schema": { 
       "$ref": "#/definitions/errorModel" 
      } 
      } 
     } 
     } 
    } 
    }, 
    "definitions": { 
    "pet": { 
     "required": [ 
     "id", 
     "name" 
     ], 
     "externalDocs": { 
     "description": "find more info here", 
     "url": "https://helloreverb.com/about" 
     }, 
     "properties": { 
     "id": { 
      "type": "integer", 
      "format": "int64" 
     }, 
     "name": { 
      "type": "string" 
     }, 
     "tag": { 
      "type": "string" 
     } 
     } 
    }, 
    "newPet": { 
     "allOf": [ 
     { 
      "$ref": "pet" 
     }, 
     { 
      "required": [ 
      "name" 
      ], 
      "properties": { 
      "id": { 
       "type": "integer", 
       "format": "int64" 
      } 
      } 
     } 
     ] 
    }, 
    "errorModel": { 
     "required": [ 
     "code", 
     "message" 
     ], 
     "properties": { 
     "code": { 
      "type": "integer", 
      "format": "int32" 
     }, 
     "message": { 
      "type": "string" 
     } 
     } 
    } 
    } 
}