Search code examples
swaggerswagger-editor

How do I get markdown to work in Swagger model descriptions?

I am trying to add extra information to model items in Swagger. The documentation says that GFM syntax can be used in description fields but this is not working in all places.

Here is a minimal dummy example of the problem:

swagger: '2.0'
info:
  title: Example API
  description: (1) This is the API description containing some *rich* **text**
  version: "1.0.0"
paths:
  /products:
    get:
      summary: Product Types
      description: (2) This is the path description also containing some *rich* **text**

      responses:
        200:
          description: (3) This is a response description also containing some *rich* **text**
          schema:
            type: array
            items:
              $ref: '#/definitions/Product'

definitions:
  Product:
    description: (4) This is a model description where *rich* **text** does not work
    type: object
    properties:
      product_id:
        type: string
        description: (5) This is a field description where *rich* **text** does not work

Output from Swagger editor

The schema object documentation says that I should be able to use Markdown in the place marked as (4) above but doesn't say anything about place (5).

I want to add Markdown to either of the two places in the Model section. How can I get this to work?

Solution

  • Swagger Editor does not support Markdown in model descriptions. From https://github.com/swagger-api/swagger-editor/issues/682:

    For rendering JSON Schema object we are using json-schema-view-js lib which does not support Markdown. Swagger Editor can not change behavior of this lib and this behavior is not something common to add to the lib.

    If you need this feature you could fork swagger-editor and/or json-schema-view-js and implement the feature/fix yourself, then submit a pull request.