Load HTML into Swagger Docs Implementation Notes

Question

I'm attempting to display HTML for my implementation notes for a given endpoint using Swagger Docs. Below, I've typed out the HTML as a string, but I love to load these in as a module of some sort, so that I can simply edit HTML files separately.

I couldn't find an answer in the Google Group and I'd like to see if this is something that is already solved before I create some sort of grunt plug-in to handle it.

Here's my current code:

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"
    }]
[...]

Is there a cleaner way to implement this?

Are you aware that Swagger 2.0 supports GFM for most description and info fields? — Ron
– Ron, Commented Feb 10, 2015 at 15:26
Are you suggesting that I can edit .md files and load them into the description fields? That would be sweet. A few cursory searches didn't yield much in that regard. A link to some docs on that would be cool — d2burke
– d2burke, Commented Feb 10, 2015 at 15:30
You would have to include them in the spec itself. You can't reference external documentation from those fields. However, with Swagger 2.0 there's also the option to include externalDocs for many of the properties, which could lead to virtually anything. How this is not yet implemented in the UI, should be available in M2. — Ron
– Ron, Commented Feb 10, 2015 at 15:43
So...i'd still be hard-coding it all into the JSON, but using MD instead of HTML? Ok, that's still an improvement on what I have. I'd love to see and external solution though. Thanks @Ron — d2burke
– d2burke, Commented Feb 10, 2015 at 15:49
The externalDocs would be dynamic as it's just a URL to whatever you want. — Ron
– Ron, Commented Feb 10, 2015 at 15:51

Ron · Accepted Answer · 2015-02-10 15:58:54Z

Swagger 2.0 adds some more flexibility with rich documentation.

One way, is the ability to add markdown tags (GFM flavor) to the description fields.

Another way, is to use the externalDocs property where applicable to add an external documentation resource. An example for it would be:

{
  "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": "[email protected]",
      "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"
        }
      }
    }
  }
}

ok...I think I see what you're getting at now. Essentially, there is no other way to dynamically load HTML or MD into the fields. I can only link to external docs, which is not what I want here. Do I understand you correctly? I want to edit separate html or md files and load them into the notes field.
The spec is a static file. Its generation can be dynamic, but when it is loaded by any tool, it will be static. Whether you can dynamically load HTML or MD into the fields would depend on the capabilities of the tools you use. I don't know of any tool that currently supports it, but that shouldn't stop you from opening a feature request on your tool of choice.

Collectives™ on Stack Overflow

Load HTML into Swagger Docs Implementation Notes

1 Answer 1

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related