apiaryio / drafter Goto Github PK

API Blueprint Parser (C++)

License: MIT License

Ruby 0.02% Makefile 0.04% Python 24.31% C++ 62.77% C 0.16% API Blueprint 11.54% Batchfile 0.14% Gherkin 0.06% Shell 0.13% Emacs Lisp 0.28% Dockerfile 0.01% CMake 0.54%

api-blueprint

drafter's People

Stargazers

Watchers

drafter's Issues

Nested arrays are not parsed correctly

The nested array object is not correctly parsed using drafter, see the example API Blueprint below.
In Apiary I can see render only

{
  "categories": [
    {
      "name": "Category One",
      "subcategories": []
    }
  ]
}

instead of

{
  "categories": [
    {
      "name": "Category One",
      "subcategories":
      [
        {
          "name": "Sub category One"
        }
      ]
    }
  ]
}

Example Blueprint

FORMAT: 1A

# Test nested arrays-in-object-arrays

A navigation has multiple categories. Each category can have multiple subcategories.

# GET /navigation

+ Response 200 (application/json)

    + Attributes

        + categories (array)
            + (object)
                + name: Category One (string) - Name of the category
                + subcategories (array)
                    + (object)
                        + name: Sub category One (string) - Name of the subcategory

EDIT by @pksunkara: The MSON AST which is generated from the blueprint is wrong.

Distinguish business warnings from HTTP spec violations

@zdne opened apiaryio/snowcrash#51

Usually parser warnings are treated very seriously; maybe differ between business error and HTTP spec violation

MSON: Complex samples are parsed as distinct values

@honzajavorek opened apiaryio/snowcrash#286

Protagonist version

"protagonist-experimental": "0.18.2"

MSON Specs

https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#44-sample

Example MSON (copy pasted from specs)

- list: *3, 4* (enum)

Result of parsing

{
  "name": {
    "literal": "...",
    "variable": false
  },
  "sections": [
    {
      "class": "memberType",
      "content": [
        {
          "class": "property",
          "content": {
            "name": {
              "literal": "list"
            },
            "valueDefinition": {
              "values": [
                {
                  "literal": "*3",
                  "variable": false
                },
                {
                  "literal": "4*",
                  "variable": false
                }
              ],
              "typeDefinition": {
                "typeSpecification": {
                  "name": "enum"
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Expected

Probably sth like

                {
                  "literal": "3",
                  "variable": true
                },
                {
                  "literal": "4",
                  "variable": true
                }

Other possible option: the spec is wrong.

Support tabs and CRLF line endings

@zdne opened apiaryio/snowcrash#29

Report not allowed characters in identifiers

@zdne opened apiaryio/snowcrash#41

Currently only some characters are allowed in API Blueprint identifiers.

If illegal character is used the whole section is silently ignored.

Following blueprint should at least produce a warning about illegal identifier (character ')

# Group Parcel 
## Parcel's sticker [/parcels/{parcel_id}/stickers.json]

Error: JSON schema validates value as String if no type is given

When you provide following MSON which is interpreted in MSON documentation as a key with null value.

### Some object definition
- someKeyWithNoAdditionalSpec

it results into this JSON schema wth a string type:

{  
   "type":"object",
   "properties":{  
      "someKeyWithNoAdditionalSpec":{  
         "type":"string"
      }
   },
   "$schema":"http://json-schema.org/draft-04/schema#"
}

It should only validate presence of the key until support of null primitive type in MSON imho.

Unrecognized param

@Neamar opened apiaryio/snowcrash#90

(not sure i'm posting on right repo, since i'm using API blueprint from @danielgtaylor Aglio)

My API allow for parameters prefixed with "@", for instance "@name=".
However, describing such an endpoint result in the following error:

>> Line 134: ignoring unrecognized list item, expected parameter discussion, e.g. '<parameter name> ... lorem ipsum' (warning code 5)

Where line 134 is:

+ Parameters
    + @meta (optional, string, `John`) ... Full text search on `meta` key.  Replace `meta` with the name of the meta you wish to search on.

However, i believe such a parameter is actually valid HTTP. Would it be possible to improve snowcrash to handle this use case ? (and possibly more exotic charsets).

I tried to HTML escape / encodeURIComponent without success.

drafter as dependency of other libraries => undefined references

Been a while since I wrote C++, so for dependency management I was thinking to just extract the relevant libraries to the ./lib directory of my project and work from there. I'm using CMake BTW. Here's my ./lib:

./drafter:
cdrafter.cc  drafter.h        SerializeAST.h      SerializeSourcemap.cc
cdrafter.h   main.cc          Serialize.cc        SerializeSourcemap.h
config.cc    reporting.cc     Serialize.h         stream.h
config.h     reporting.h      SerializeResult.cc  Version.h
drafter.cc   SerializeAST.cc  SerializeResult.h

./markdownparser:
ByteBuffer.cc  MarkdownNode.cc  MarkdownParser.cc
ByteBuffer.h   MarkdownNode.h   MarkdownParser.h

./snowcrash:
ActionParser.h              MSONUtility.h
AssetParser.h               MSONValueMemberParser.cc
AttributesParser.h          MSONValueMemberParser.h
Blueprint.cc                ParameterParser.h
Blueprint.h                 ParametersParser.h
BlueprintParser.h           PayloadParser.h
BlueprintSourcemap.cc       Platform.h
BlueprintSourcemap.h        posix
BlueprintUtility.h          RegexMatch.h
CodeBlockUtility.h          RelationParser.h
DataStructureGroupParser.h  ResourceGroupParser.h
HeadersParser.cc            ResourceParser.h
HeadersParser.h             Section.cc
HTTP.cc                     Section.h
HTTP.h                      SectionParserData.h
ModelTable.h                SectionParser.h
MSON.cc                     SectionProcessor.h
MSON.h                      Signature.cc
MSONMixinParser.h           Signature.h
MSONNamedTypeParser.h       SignatureSectionProcessor.h
MSONOneOfParser.cc          snowcrash.cc
MSONOneOfParser.h           snowcrash.h
MSONParameterParser.h       SourceAnnotation.h
MSONPropertyMemberParser.h  StringUtility.h
MSONSourcemap.cc            UriTemplateParser.cc
MSONSourcemap.h             UriTemplateParser.h
MSONTypeSectionParser.cc    ValuesParser.h
MSONTypeSectionParser.h     win

./snowcrash/posix:
RegexMatch.cc

./snowcrash/win:
RegexMatch.cc

./sos:
sos.cc  sos.h  sosJSON.h  sosYAML.h

./sundown:
autolink.c  buffer.c  html_blocks.h  markdown.h  src_map.h  stack.h
autolink.h  buffer.h  markdown.c     src_map.c   stack.c

…and here's the error:

Linking CXX executable project_name
CMakeFiles/project_name.dir/src/main.cpp.o: In function `main':
project_name/src/main.cpp:21: undefined reference to `drafter::ParseBlueprint(std::string const&, unsigned int, snowcrash::ParseResultRef<snowcrash::Blueprint> const&)'
project_name/src/main.cpp:26: undefined reference to `drafter::WrapBlueprint(snowcrash::Blueprint const&)'
project_name/src/main.cpp:26: undefined reference to `sos::Serialize::process(sos::Base const&, std::ostream&, unsigned long)'
CMakeFiles/project_name.dir/src/main.cpp.o: In function `snowcrash::SourceAnnotation::SourceAnnotation()':
project_name/lib/drafter/../snowcrash/SourceAnnotation.h:37: undefined reference to `snowcrash::SourceAnnotation::OK'
CMakeFiles/project_name.dir/src/main.cpp.o: In function `sos::SerializeJSON::string(std::string const&, std::ostream&)':
project_name/lib/sos/sosJSON.h:32: undefined reference to `sos::escapeBackslashes(std::string const&)'
project_name/lib/sos/sosJSON.h:33: undefined reference to `sos::escapeDoubleQuotes(std::string const&)'
project_name/lib/sos/sosJSON.h:34: undefined reference to `sos::escapeNewlines(std::string const&)'
CMakeFiles/project_name.dir/src/main.cpp.o: In function `sos::SerializeJSON::array(sos::Base const&, std::ostream&, unsigned long)':
project_name/lib/sos/sosJSON.h:53: undefined reference to `sos::Base::array() const'
project_name/lib/sos/sosJSON.h:58: undefined reference to `sos::Base::array() const'
project_name/lib/sos/sosJSON.h:60: undefined reference to `sos::Base::array() const'
project_name/lib/sos/sosJSON.h:65: undefined reference to `sos::Serialize::process(sos::Base const&, std::ostream&, unsigned long)'
project_name/lib/sos/sosJSON.h:58: undefined reference to `sos::Base::array() const'
CMakeFiles/project_name.dir/src/main.cpp.o: In function `sos::SerializeJSON::object(sos::Base const&, std::ostream&, unsigned long)':
project_name/lib/sos/sosJSON.h:94: undefined reference to `sos::Base::object() const'
project_name/lib/sos/sosJSON.h:94: undefined reference to `sos::Serialize::process(sos::Base const&, std::ostream&, unsigned long)'
CMakeFiles/project_name.dir/src/main.cpp.o: In function `snowcrash::Blueprint::~Blueprint()':
project_name/lib/drafter/../snowcrash/Blueprint.h:476: undefined reference to `snowcrash::Element::~Element()'
CMakeFiles/project_name.dir/src/main.cpp.o: In function `snowcrash::SourceMap<snowcrash::Blueprint>::~SourceMap()':
project_name/lib/drafter/../snowcrash/BlueprintSourcemap.h:330: undefined reference to `snowcrash::SourceMap<snowcrash::Element>::~SourceMap()'
CMakeFiles/project_name.dir/src/main.cpp.o: In function `sos::SerializeJSON::SerializeJSON()':
project_name/lib/sos/sosJSON.h:16: undefined reference to `sos::Serialize::Serialize()'
CMakeFiles/project_name.dir/src/main.cpp.o: In function `snowcrash::Blueprint::Blueprint()':
project_name/lib/drafter/../snowcrash/Blueprint.h:476: undefined reference to `snowcrash::Element::Element(snowcrash::Element::Class const&)'
project_name/lib/drafter/../snowcrash/Blueprint.h:476: undefined reference to `snowcrash::Element::~Element()'
CMakeFiles/project_name.dir/src/main.cpp.o: In function `snowcrash::SourceMap<snowcrash::Blueprint>::SourceMap()':
project_name/lib/drafter/../snowcrash/BlueprintSourcemap.h:330: undefined reference to `snowcrash::SourceMap<snowcrash::Element>::SourceMap(snowcrash::Element::Class const&)'
collect2: error: ld returned 1 exit status
CMakeFiles/project_name.dir/build.make:85: recipe for target 'project_name' failed
make[3]: *** [project_name] Error 1
CMakeFiles/Makefile2:60: recipe for target 'CMakeFiles/project_name.dir/all' failed
make[2]: *** [CMakeFiles/project_name.dir/all] Error 2
CMakeFiles/Makefile2:72: recipe for target 'CMakeFiles/project_name.dir/rule' failed
make[1]: *** [CMakeFiles/project_name.dir/rule] Error 2
Makefile:109: recipe for target 'project_name' failed
make: *** [project_name] Error 2

Refactor StatusCodeTraits and HTTPMethodTraits

@pksunkara opened apiaryio/snowcrash#99

In my opinion, a single Traits should be enough which would check both http methond and response status code.

Warn on method names that are not uppercase

@Almad opened apiaryio/snowcrash#334

Warnings are confusing if method name is not written all-CAPS and therefore not recognised.

Snowcrash should recognise the line (be case-insensitive) and issue a warning.

Fore more details, see this SO question

Non-functional reference-style links

@zdne opened apiaryio/snowcrash#55

Update: This is no longer the issue, however there is still a problem when the reference is defined in another description block. See apiaryio/snowcrash#55 (comment)

~~Following blueprint:~~

# API
This is [an example][id] reference-style link.

[id]: http://example.com "x"

~~renders as:~~

_version: 1.0
metadata:
name: API
description: "This is [an example][id] reference-style link.\n\n["
resourceGroups:

Refer to Markdown Link Syntax

Well behaved command line tools return >0 on error.

Might it be appropriate for drafter to exit with a non-zero status if it encountered any errors or warnings during execution? It makes it difficult to script when it does not conform to common practices.

Refactor StatusCodeTraits and HTTPMethodTraits

@pksunkara opened apiaryio/snowcrash#99

In my opinion, a single Traits should be enough which would check both http methond and response status code.

Error in compiling on Win8 LNK1104 cannot open file kernel32.lib

Dear all,

I want to use drafter on win 8 but it has lots of problem when I want to compile it on windows.

1- First of all with VS Express you don't have Command line compiler. Then I needed to install the full version. See the error below:

C:\Users\xxx\Documents\GitHub\drafter>vcbuild.bat
creating config.gypi
creating config.mk
creating makefiles
Warning: Missing input files:
./build\ext\snowcrash\..\..\..\ext\snowcrash\src\Version.h
All OK.
Project files generated.
ERROR: Cannot determine the location of the VS Common Tools folder.
Build skipped. To build, this file needs to run from VS cmd prompt.

After that I installed the Visual studio full version. And when I wanted to compile it by running vcbuild.bat in the step "8>InitializeBuildStatus: ClCompile" I got the following error:

---------------------------
cl.exe - Systemfehler
---------------------------
Das Programm kann nicht gestartet werden, da mspdb110.dll auf dem Computer fehlt. Installieren Sie das Programm erneut, um das Problem zu beheben. 
---------------------------

It is in German but means can not find mspdb110.dll file. I found the file in the following location and add it to the system path to solve this problem:

C:\Program Files (x86)\Microsoft Visual Studio 11.0\Common7\IDE

But at the moment there are 2 new problem that I couldn't solve them by adding anymore address to the path:

The first problem:

 10>c:\users\xxxi\documents\github\drafter\test\vendor\catch\include
\internal\catch_console_colour_impl.hpp(29): fatal error C1083: 
Cannot open include file: 'windows.h': No such file or directory (..\test\test-main.cc)
[C:\Users\xxx\Documents\GitHub\drafter\build\test-libdrafter.vcxproj]

And the second one:

 9>LINK : fatal error LNK1104: cannot open file 'kernel32.lib'         
[C:\Users\xxx\Documents\GitHub\drafter\build\drafter.vcxproj]

Please help me. I also asked this question with some pictures here:

http://stackoverflow.com/questions/29878710/how-to-install-apiaryio-drafter-on-windows-8

But no any useful answer come up!

Thanks in advance.

MSON - enum bug - samples/default parsed as array

Input

Example

## GET /
+ Attributes
    + id: 20 (enum[number], optional) - Database ID

        Additional description

        + Default: 1

        + Sample: 23

+ Response 201

Result (partial):

... 
"value": {
          "element": "enum",
          "attributes": {
            "samples": [
              [
                "23"
              ]
            ],
            "default": [
              "1"
            ]
...

BUG

attributes.samples and attributes.default saved as array
individual values are typed as "StringElement" - it should hold type specification from enum[number]

Unrecognized param

@Neamar opened apiaryio/snowcrash#90

(not sure i'm posting on right repo, since i'm using API blueprint from @danielgtaylor Aglio)

My API allow for parameters prefixed with "@", for instance "@name=".
However, describing such an endpoint result in the following error:

>> Line 134: ignoring unrecognized list item, expected parameter discussion, e.g. '<parameter name> ... lorem ipsum' (warning code 5)

Where line 134 is:

+ Parameters
    + @meta (optional, string, `John`) ... Full text search on `meta` key.  Replace `meta` with the name of the meta you wish to search on.

However, i believe such a parameter is actually valid HTTP. Would it be possible to improve snowcrash to handle this use case ? (and possibly more exotic charsets).

I tried to HTML escape / encodeURIComponent without success.

MSON - Members vs. Items vs. Properties

@klokane opened apiaryio/snowcrash#330

in MSON spec 4.1.2 https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#421-member-type-separator
is written:

Member Type Separator → Items | Members | Properties
Array Structures - MUST use Items for a Member Type Separator
Enum Structures - MUST use Members for a Member Type Separator
Object Structures - MUST use Properties for a Member Type Separator

But implementation in snowcrash it does not handle strictly:

object

allows Properties
disallow Memebers && Items

array && enum

allows both Members && Items
disallow Properties

example for parser https://gist.github.com/klokane/405aa50eaa157b8808d2

Based on discuss with @zdne there is proposal change

MSON Specification 4.2.1

all MUST to SHOULD

Snowcrash Implementation

Accept (optionaly with warning) all variants of Member Type Separator for all types of Stucture types while parsing

brew formula seems to try to clone from a tag that doesn't exist

when running brew I get:

==> Cloning https://github.com/apiaryio/drafter.git
Cloning into '/Library/Caches/Homebrew/drafter--git'...
warning: Could not find remote branch v0.1.0 to clone.
fatal: Remote branch v0.1.0 not found in upstream origin
Error: Failed to download resource "drafter"
Failure while executing: git clone --depth 1 --branch v0.1.0 https://github.com/apiaryio/drafter.git /Library/Caches/Homebrew/drafter--git

Superfluous newlines in description section lists items

@zdne opened apiaryio/snowcrash#214

Given

# API 

Before Hello

- a
- b

After Hello World

The output AST description node contains extraneous newlines after each list item.

Actual

_version: 2.0
metadata:
name: "API"
description: "Before Hello\n\n- a\n\n- b\n\nAfter Hello World\n"
resourceGroups:

Superfluous newlines in description section lists items

@zdne opened apiaryio/snowcrash#214

Given

# API 

Before Hello

- a
- b

After Hello World

The output AST description node contains extraneous newlines after each list item.

Actual

_version: 2.0
metadata:
name: "API"
description: "Before Hello\n\n- a\n\n- b\n\nAfter Hello World\n"
resourceGroups:

Report URIs without leading /

@zdne opened apiaryio/snowcrash#269

Following resource is silently ignored

# Resource [path/to/resource]
...

Missing the leading / often leads to confusion later. Parser should warn about possible URIs.

validation and sourcemap are probably mutually exclusive but no info is given

When I run drafter -l -s source.map api.apib the source map is not generated but drafter is not signaling it in any way. It should say at least something like ignoring source map when only validating or so.

Report URIs without leading /

@zdne opened apiaryio/snowcrash#269

Following resource is silently ignored

# Resource [path/to/resource]
...

Missing the leading / often leads to confusion later. Parser should warn about possible URIs.

Snowcrash should warn when blueprint specifies Request with GET method

@Almad opened apiaryio/snowcrash#64

With GET, there should be no request body.

When it's specified in blueprint, snowcrash should warn or err.

Support tabs and CRLF line endings

@zdne opened apiaryio/snowcrash#29

MSON: Complex samples are parsed as distinct values

@honzajavorek opened apiaryio/snowcrash#286

Protagonist version

"protagonist-experimental": "0.18.2"

MSON Specs

https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#44-sample

Example MSON (copy pasted from specs)

- list: *3, 4* (enum)

Result of parsing

{
  "name": {
    "literal": "...",
    "variable": false
  },
  "sections": [
    {
      "class": "memberType",
      "content": [
        {
          "class": "property",
          "content": {
            "name": {
              "literal": "list"
            },
            "valueDefinition": {
              "values": [
                {
                  "literal": "*3",
                  "variable": false
                },
                {
                  "literal": "4*",
                  "variable": false
                }
              ],
              "typeDefinition": {
                "typeSpecification": {
                  "name": "enum"
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Expected

Probably sth like

                {
                  "literal": "3",
                  "variable": true
                },
                {
                  "literal": "4",
                  "variable": true
                }

Other possible option: the spec is wrong.

Un-escape HTML entities

@zdne opened apiaryio/snowcrash#42

HTML entities such as — should be escaped in non-description nodes (e.g. name).

In description nodes of AST it should be controlled by the rendering parser flag.

# A &mdash; Z API

Lorem &mdash; Ipsum

Maximum call stack size exceeded

I got the following error while trying to parse an apib file. See below. Can you please advise on this?

It looks like an app stack size is reached. Is there any way to increase app stack size globally?

RangeError: Maximum call stack size exceeded
at /usr/local/lib/node_modules/aglio/node_modules/drafter/node_modules/boutique/lib/inspect.js:200:5
at Object.hasAnyMemberSections (/usr/local/lib/node_modules/aglio/node_modules/drafter/node_modules/boutique/lib/inspect.js:208:5)
at isObject (/usr/local/lib/node_modules/aglio/node_modules/drafter/node_modules/boutique/lib/typeresolution.js:61:18)
at resolveImplicitType (/usr/local/lib/node_modules/aglio/node_modules/drafter/node_modules/boutique/lib/typeresolution.js:75:11)
at /usr/local/lib/node_modules/aglio/node_modules/drafter/node_modules/boutique/lib/typeresolution.js:126:14
at simplifyTypeSpecification (/usr/local/lib/node_modules/aglio/node_modules/drafter/node_modules/boutique/lib/typeresolution.js:41:12)
at resolveType (/usr/local/lib/node_modules/aglio/node_modules/drafter/node_modules/boutique/lib/typeresolution.js:121:10)
at handleElement (/usr/local/lib/node_modules/aglio/node_modules/drafter/node_modules/boutique/lib/formats/jsonschema-v4.js:533:10)
at resolveProperty (/usr/local/lib/node_modules/aglio/node_modules/drafter/node_modules/boutique/lib/formats/jsonschema-v4.js:46:10)
at /usr/local/lib/node_modules/aglio/node_modules/drafter/node_modules/boutique/lib/formats/jsonschema-v4.js:61:12

Source maps should not be printed if no option is given

@klokane This is priority. Please fix this first. And also add an integration test.

pksunkara@apicave [drafter] #180 «pksunkara/update» →  ./bin/drafter 
# My API

What's up
_version: "3.0"
metadata: []
name: "My API"
description: "What's up\n"
element: "category"
resourceGroups: []
content: []
metadata: []
name: []
description: []
resourceGroups: []
content: []

OK.

The output AST should only be this:

_version: "3.0"
metadata: []
name: "My API"
description: "What's up\n"
element: "category"
resourceGroups: []
content: []

Warning for empty sample

@klokane opened apiaryio/snowcrash#331

there should be added warning about empty sample

# <API name>
<API description>

# Data Structures

## User (object)
- a (array)
    - sample

Report possible keywords

@zdne opened apiaryio/snowcrash#65

For example in

# Resource [/]
+ Model
    + Body (application/json)

            { ... }

The + Body (application/json) is not recognized as a body (content type should be defined on the model level) and thus the whole list item is considered to be model's description.

MSON - Members vs. Items vs. Properties

@klokane opened apiaryio/snowcrash#330

in MSON spec 4.1.2 https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#421-member-type-separator
is written:

Member Type Separator → Items | Members | Properties
Array Structures - MUST use Items for a Member Type Separator
Enum Structures - MUST use Members for a Member Type Separator
Object Structures - MUST use Properties for a Member Type Separator

But implementation in snowcrash it does not handle strictly:

object

allows Properties
disallow Memebers && Items

array && enum

allows both Members && Items
disallow Properties

example for parser https://gist.github.com/klokane/405aa50eaa157b8808d2

Based on discuss with @zdne there is proposal change

MSON Specification 4.2.1

all MUST to SHOULD

Snowcrash Implementation

Accept (optionaly with warning) all variants of Member Type Separator for all types of Stucture types while parsing

Non-indented Body under Response in an action

@pksunkara opened apiaryio/snowcrash#148

If you look here

## GET /1

+ Response 200

+ Body

        {}

casually ignores the Body node and sets the Response body as empty.

We can improve this by adding the Body's asset to Response.

Parser harness features

This is a placeholder for discussion that started at apiaryio/snowcrash#57.

Since we finally have a (dummy) drafter any related discussion should continue here.

Report keywords in description headers

@zdne opened apiaryio/snowcrash#31

Following blueprint is parsed as with API Name POST and the rest of keywords as a API description. Parser should warn about this.

FORMAT: X-1A

## POST 

+ Request

+ Header 

``` 
lorem ipsum
``` 

+ Body 

``` 
{ 
lorem ipsum
}
```

Make sure properties get overridden successfully

Using the current boutique.js, when we are expanding MSON of the following blueprint, the properties of an object, doesn't get overridden correctly and contains duplicates.

FORMAT: 1A
HOST: http://parametrizedmson.apiblueprint.org/

# Testing parametrized MSON

Just testing parametrized MSON.

# Resource A [/a]
## Create [GET]
+ request (application/json)
  + attributes (A)

+ response 201

+ request (application/json)
  + attributes (A)
      + a2: 42

+ response 400



# Data Structures
## A (object)
+ a1: 1
+ a2: 2

The rendered JSON should be

{
  "a1": "1",
  "a2": "42"
}

And the MSON table should be the following

Name	Type	Required	Description	Value
a1	optional	1
a2	optional	2

The MSON table is currently the following

Name	Type	Required
a2	optional	42
a1	optional	1
a2	optional	2

Warn on method names that are not uppercase

@Almad opened apiaryio/snowcrash#334

Warnings are confusing if method name is not written all-CAPS and therefore not recognised.

Snowcrash should recognise the line (be case-insensitive) and issue a warning.

Fore more details, see this SO question

Cryptic error codes when using `drafter_c_parse`

When using the simple parsing function int drafter_c_parse() the return value of not zero is quite cryptic. To figure out what the value actually means one has to dig deep into snowcrash to find out and even then it's not really obvious what the problem is. Would it be possible to provide an interface to get detailed description of the error? Either classic strerror or some other way like if error != 0 the *result will contain error description.

MSON - array|enum samples wrong parsed

@klokane opened apiaryio/snowcrash#327

according to MSON spec:
https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#44-sample

- list: 3, 4 (enum, sample)

Is equivalent to:

- list: *3, 4* (enum)

but if you sent it to snowcrash, following blueprint:

# <API name>
<API description>

# Data Structures

## User (object)
- list1: 3, 4 (enum, sample)
- list2: *3, 4* (enum)

Result is following:

_version: "3.0"
metadata: []
name: "<API name>"
description: "<API description>\n\n"
element: "category"
resourceGroups: []
content:
  -
    element: "category"
    content:
      -
        element: "dataStructure"
        name:
          literal: "User"
          variable: false
        typeDefinition:
          typeSpecification:
            name: "object"
            nestedTypes: []
          attributes: []
        sections:
          -
            class: "memberType"
            content:
              -
                content:
                  name:
                    literal: "list1"
                  description: ""
                  valueDefinition:
                    values:
                      -
                        literal: "3"
                        variable: false
                      -
                        literal: "4"
                        variable: false
                    typeDefinition:
                      typeSpecification:
                        name: "enum"
                        nestedTypes: []
                      attributes:
                        - "sample"
                  sections: []
                class: "property"
              -
               content:
                  name:
                    literal: "list2"
                  description: ""
                  valueDefinition:
                    values:
                      -
                        literal: "*3"
                        variable: false
                      -
                        literal: "4*"
                        variable: false
                    typeDefinition:
                      typeSpecification:
                        name: "enum"
                        nestedTypes: []
                      attributes: []
                  sections: []
                class: "property"

list1 has sample atribute, list2 has no. And valueDefinition are in both cases different too

Distinguish business warnings from HTTP spec violations

@zdne opened apiaryio/snowcrash#51

Usually parser warnings are treated very seriously; maybe differ between business error and HTTP spec violation

Report possible keywords

@zdne opened apiaryio/snowcrash#65

For example in

# Resource [/]
+ Model
    + Body (application/json)

            { ... }

The + Body (application/json) is not recognized as a body (content type should be defined on the model level) and thus the whole list item is considered to be model's description.

Non-indented Body under Response in an action

@pksunkara opened apiaryio/snowcrash#148

If you look here

## GET /1

+ Response 200

+ Body

        {}

casually ignores the Body node and sets the Response body as empty.

We can improve this by adding the Body's asset to Response.

Measure `ParseBlueprint()` performance

Add option to measure and report time spent in ParseBlueprint().

Future: consider setting a parsing timeout and abort parsing when timeout is reached.

Snowcrash should warn when blueprint specifies Request with GET method

@Almad opened apiaryio/snowcrash#64

With GET, there should be no request body.

When it's specified in blueprint, snowcrash should warn or err.

Non-functional reference-style links

@zdne opened apiaryio/snowcrash#55

Update: This is no longer the issue, however there is still a problem when the reference is defined in another description block. See apiaryio/snowcrash#55 (comment)

~~Following blueprint:~~

# API
This is [an example][id] reference-style link.

[id]: http://example.com "x"

~~renders as:~~

_version: 1.0
metadata:
name: API
description: "This is [an example][id] reference-style link.\n\n["
resourceGroups:

Refer to Markdown Link Syntax

Report not allowed characters in identifiers

@zdne opened apiaryio/snowcrash#41

Currently only some characters are allowed in API Blueprint identifiers.

If illegal character is used the whole section is silently ignored.

Following blueprint should at least produce a warning about illegal identifier (character ')

# Group Parcel 
## Parcel's sticker [/parcels/{parcel_id}/stickers.json]

Warning for empty sample

@klokane opened apiaryio/snowcrash#331

there should be added warning about empty sample

# <API name>
<API description>

# Data Structures

## User (object)
- a (array)
    - sample

MSON - array|enum samples wrong parsed

@klokane opened apiaryio/snowcrash#327

according to MSON spec:
https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#44-sample

- list: 3, 4 (enum, sample)

Is equivalent to:

- list: *3, 4* (enum)

but if you sent it to snowcrash, following blueprint:

# <API name>
<API description>

# Data Structures

## User (object)
- list1: 3, 4 (enum, sample)
- list2: *3, 4* (enum)

Result is following:

_version: "3.0"
metadata: []
name: "<API name>"
description: "<API description>\n\n"
element: "category"
resourceGroups: []
content:
  -
    element: "category"
    content:
      -
        element: "dataStructure"
        name:
          literal: "User"
          variable: false
        typeDefinition:
          typeSpecification:
            name: "object"
            nestedTypes: []
          attributes: []
        sections:
          -
            class: "memberType"
            content:
              -
                content:
                  name:
                    literal: "list1"
                  description: ""
                  valueDefinition:
                    values:
                      -
                        literal: "3"
                        variable: false
                      -
                        literal: "4"
                        variable: false
                    typeDefinition:
                      typeSpecification:
                        name: "enum"
                        nestedTypes: []
                      attributes:
                        - "sample"
                  sections: []
                class: "property"
              -
               content:
                  name:
                    literal: "list2"
                  description: ""
                  valueDefinition:
                    values:
                      -
                        literal: "*3"
                        variable: false
                      -
                        literal: "4*"
                        variable: false
                    typeDefinition:
                      typeSpecification:
                        name: "enum"
                        nestedTypes: []
                      attributes: []
                  sections: []
                class: "property"

list1 has sample atribute, list2 has no. And valueDefinition are in both cases different too

Report keywords in description headers

@zdne opened apiaryio/snowcrash#31

Following blueprint is parsed as with API Name POST and the rest of keywords as a API description. Parser should warn about this.

FORMAT: X-1A

## POST 

+ Request

+ Header 

``` 
lorem ipsum
``` 

+ Body 

``` 
{ 
lorem ipsum
}
```

Un-escape HTML entities

@zdne opened apiaryio/snowcrash#42

HTML entities such as — should be escaped in non-description nodes (e.g. name).

In description nodes of AST it should be controlled by the rendering parser flag.

# A &mdash; Z API

Lorem &mdash; Ipsum

apiaryio / drafter Goto Github PK

drafter's People

Stargazers

Watchers

Forkers

drafter's Issues

Protagonist version

MSON Specs

Example MSON (copy pasted from specs)

Result of parsing

Expected

Input

Result (partial):

BUG

object

array && enum

MSON Specification 4.2.1

Snowcrash Implementation

Given

Actual

Given

Actual

Protagonist version

MSON Specs

Example MSON (copy pasted from specs)

Result of parsing

Expected

object

array && enum

MSON Specification 4.2.1

Snowcrash Implementation

Recommend Projects

Recommend Topics

Recommend Org