URI Template without leading slash doesn't get recognized

[honzajavorek]

Given following API Blueprint

FORMAT: 1A

# Cats API

# User Authentication [GET v6/auth]

Logins an a user and gives them an accesss token

+ Request (application/json)

        {
            "username": "[email protected]",
            "password": "test"
        }

+ Response 200 (application/json)

        {
            "access_token": "RandomStringForAuth"
        }

I get following output from Drafter:

element: "parseResult"
content:
  -
    element: "category"
    meta:
      classes:
        - "api"
      title: "Cats API"
    attributes:
      meta:
        -
          element: "member"
          meta:
            classes:
              - "user"
          content:
            key:
              element: "string"
              content: "FORMAT"
            value:
              element: "string"
              content: "1A"
    content:
      -
        element: "copy"
        content: "# User Authentication [GET v6/auth]\n\nLogins an a user and gives them an accesss token\n\n+ Request (application/json)\n\n        {\n            \"username\": \"[email protected]\",\n            \"password\": \"test\"\n        }\n\n+ Response 200 (application/json)\n\n        {\n            \"access_token\": \"RandomStringForAuth\"\n        }"

Drafter completely ignores the User Authentication [GET v6/auth] section. This isn't very user-friendly. It's quite clear user just forgot to start the URI Template with a leading slash character. Drafter should be able to read such markup with a warning. Fixing the markup to # User Authentication [GET /v6/auth] works.

This is a follow-up to a real, user-reported developer experience glitch: apiaryio/dredd#261 Possibly related also to #350

[pksunkara]

This is intentional if I remember. We use the leading slash to recognise that it's an uri. Otherwise, we can't distinguish from normal text and uri.

[honzajavorek]

@pksunkara I'd say it's not very hard to detect it's meant to be an URI in this case. Something like:

• if the heading contains [http-verb anything-else-than-closing-bracket]

If we want to be strict, we could add:

• ...and anything-else-than-closing-bracket contains at least one slash

I think it's very easy to do the error of not having the leading slash and it's not very clear from the parser output what's the problem with such blueprint. Maybe if parser detects a heading according to rules I described, it could still ignore it, but add a warning, which says the blueprint contains something which 99% looks like user mistake and user can fix it with leading slash.

[w-vi]

I think it should produce a warning helping to see if it is intentional or not.

[kylef]

We should already be causing a warning for this in some cases: https://github.com/apiaryio/snowcrash/blob/master/src/ActionParser.h#L548. For some reason this case is not being check as it is not an action.

[pksunkara]

It is sometimes hard to recognise some cases.

[kylef]

Linking together apiaryio/snowcrash#269