# safe-markdown

Source: https://apigenie.pl/docs/linter/swagger/rules/safe-markdown

A rule of the Swagger 2.0 linter, which reads Swagger 2.0 documents; OpenAPI 3 documents go to the OpenAPI linter. Since 0.9.0. Fixed by `--fix`. In the rulesets: Recommended at warning, Strict at error, All at error.

This rule ensures that the GFM descriptions of a Swagger 2.0 document do not
contain unsafe constructs like `script` elements or `eval()` calls.

## Rule details

Unsafe constructs embedded in descriptions can pose security risks when the
documentation is rendered, for example by a documentation portal or an API
console.

The `safe-markdown` rule checks the `description` field of the info object,
operations, parameters, responses (but not response references), headers,
schemas, security definitions, tags and external documentation objects. It
reports:

- `Markdown contains <script> tag` when a description contains a `script`
  element (an opening tag followed by a closing tag),
- `Markdown contains eval() function` when a description contains `eval`
  followed by a parenthesized argument list.

Both checks are case-insensitive, and skip code spans and code blocks.

The OpenAPI and AsyncAPI linters have rules of the same name,
[safe-markdown](/docs/linter/openapi/rules/safe-markdown) and
[safe-markdown](/docs/linter/asyncapi/rules/safe-markdown).

## Examples

**Good**.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
  description: Manages the pets of a shelter and their adoptions.
paths: {}
```

**Bad**.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
  description: "Manages the pets of a shelter. <script>alert('Unsafe')</script>"
paths:
  /pets:
    get:
      description: Evaluates eval(filter) on the server.
      responses:
        '200':
          description: The list of pets.
```

## Automatic fixes

When invoked with `--fix`, the rule rewrites the affected descriptions: the
`<` of the opening and closing `script` tags is replaced with `&lt;`, and the
`(` after `eval` with `&#40;`. The rest of the description, including code
spans and code blocks, is preserved.
