Multi-line literals in swagger editor?

yaml swagger indentation swagger-editor
fool4jesus picture fool4jesus · Jan 27, 2015 · Viewed 35.3k times · Source

I am trying to get a multi-line literal in Swagger editor (awesome tool, by the way!).

  post:
    summary: Translate one or more identifiers
    description: |
Translate one or more identifiers for one entity into the
identifiers of another entity. Translate one or more
identifiers for one entity into the identifiers of another entity.

    consumes:
    - application/json

I've tried it with | and >, with different endings (increasing indent vs. empty line), and every way I can think of, but it always gives the same error:

YAML Syntax Error
Can not read a block mapping entry; a multiline key may not be an implicit  
key at line 24, column 15: consumes: ^

I see bugs for JS-YAML that indicate the problem is a Windows-style newline at the end, which I know HTML textareas can create. This is the first time I'm really using YAML much, so is it just me doing something wrong, or a bug in Swagger editor?

Answer

Mike Malloy picture Mike Malloy · Jan 27, 2015

I believe the problem is the way you started the text on your description block. It must be indented one level to the right of description: Here's an example of something that works for me:

/{user-id}:
get:
  summary: Facebook User
  description: |
    Displays all information about a Facebook user, depending on access privileges.  Displays all information about a Facebook user, depending on access privileges.
  parameters:
    - name: user-id
      in: path
      description: The Facebook user ID
      required: true
      type: string

In my actual code, the description is three lines long.

Related questions

Converting Swagger specification JSON to HTML documentation

For some REST APIs written in PHP, I was asked to create Swagger documentation, and since I was not aware of any easy way of adding annotations to those existing APIs and create such a documentation, I used this editor …

Read More
How to escape colons and other special characters in a YAML string?

I have the following YAML fragment: description: | "API for bean consuming applications. Examples: painted pony, lima bean" Swagger editor interprets the colon (:) as a special character, despite the quotation marks. According to the accepted answer to this question, the colon …

Read More
How do you create a swagger schema that includes an array of varying types

I'm attempting to define a swagger schema definition for an object that contains an array of objects of varying types. Here is the json schema for a template object (and all related object types). I'm aware that swagger does not …

Read More