search

DINA-Web / guidelines

Guidelines on how to create, test and deploy modules within the DINA-project
2 stars 1 forks source link

add toolchain for API blueprint rendering, mock server and validation #32

Closed mskyttner closed 7 years ago

mskyttner commented 7 years ago

add Makefile with some targets using some tools for rendering validating, testing and serving .apib blueprint markdown docs - using the latest revision of the DINA-Web API Guidelines as the primary example....

a first step toward #31

more content review and some syntax changes may be needed next

mskyttner commented 7 years ago

After running the tools on the api2.md these syntax issues were listed, adding here for convenience, not sure which to use (please see Makefile init - which is the right url there?)

warn: Parser warning in file '/tmp/DINA-Web-API-Guidelines.apib': (warni ng code 10) excessive indentation, headers section is expected to be indented by just 8 spaces or 2 tabs on lines 190-191 warn: Parser warning in file '/tmp/DINA-Web-API-Guidelines.apib': (warni ng code 10) message-body asset is expected to be a pre-formatted code block, sep arate it by a newline and indent every of its line by 12 spaces or 3 tabs on lin es 244-247 warn: Parser warning in file '/tmp/DINA-Web-API-Guidelines.apib': (warni ng code 5) unexpected header block, expected a group, resource or an action defi nition, e.g. '# Group <name>', '# <resource name> [<URI>]' or '# <HTTP method> < URI>' on line 266 warn: Parser warning in file '/tmp/DINA-Web-API-Guidelines.apib': (warni ng code 10) headers is expected to be a pre-formatted code block, separate it by a newline and indent every of its line by 4 spaces or 1 tabs on lines 267-268 warn: Parser warning in file '/tmp/DINA-Web-API-Guidelines.apib': (warni ng code 9) the 'headers' section at this level is deprecated and will be removed in a future, use respective payload header section(s) instead on line 267 warn: Parser warning in file '/tmp/DINA-Web-API-Guidelines.apib': (warni ng code 5) ignoring unrecognized block on line 270 warn: Compilation warning in file '/tmp/DINA-Web-API-Guidelines.apib': A mbiguous URI parameter in template: /media/{count} Parameter not defined in API description document: count ( > Media > Retrieve co unt of all media entity types json document, paged) warn: Compilation warning in file '/tmp/DINA-Web-API-Guidelines.apib': Ambiguous URI parameter in templa te: /media/{mid}/ Parameter not defined in API description document: mid ( > Media > Retrieve all items of type {mid}, paged) warn: Compilation warning in file '/tmp/DINA-Web-API-Guidelines.apib': Ambiguous URI parameter in templa te: /media/{mid}/count Parameter not defined in API description document: mid ( > Media > Count of items of media type {mid})

mskyttner commented 7 years ago

@mikkohei13 @Inkimar I now added some updates with checklists to the release guidelines in this branch too, pls have a look!