Migration to API Elements

[netmilk]

Motivation

API Blueprint parser drafter and its Node.js binding protagonist is slowly migrating to the API Elements output format and any new functionality is no longer implemented in the legacy AST Dredd is integrated with.

Defensive prep stage

• Create an equivalent test for all API Blueprint AST based tests using the respective API Blueprint and parser in Dredd
  • Removed redundant files #417
• Do the same with blueprint-transactions
  • Created equivalents of AST-based tests, which are blueprint-based blueprint-transactions#9

The actual labour

• Fork blueprint-transactions to dredd-transactions
  • apiaryio/dredd-transactions
  • README update dredd-transactions#1
• Hide the current implementation of Cannonical Transaction Paths
  • Deprecation blueprint-transactions#10
  • README update dredd-transactions#1
• Deprecate blueprint-transactions - will no longer be maintained
  • Deprecation blueprint-transactions#10
• Reconstruct Example groups from Refract Source Maps to keep backward compatibility for Transaction Names
  • Detecting Transaction Examples dredd-transactions#2
• Switch from API Blueprint AST to API Elements
  • API Elements dredd-transactions#8
• Move parsing from Dredd to dredd-transactions
  • Support for API Elements #445
  • Change the AST input interface to an interface consuming a string on top of same fixtures using fury.js
  • Change the AST input interface to an interface consuming a string on top of same fixtures using protagonist
  • Use dredd-transactions in dredd
    • Support for API Elements #445
  • Handle errors and warnings annotations from parse result (make sure tests exist)
    • Support for API Elements #445

Unblocking

• API Blueprint Request Parameter
  • Announced here: Multiple Examples with Different Parameters  api-blueprint#310 (comment)
  • Original API Blueprint issue Response based on parameter values api-blueprint#58
  • Solves Dredd unable to correctly handle blueprint with multiple requests #78 Question: Naming transactions in multiple transactions scenario #361 ...
• Transaction Path to support multiple responses Multiple Responses aren't supported #25 (comment)
  • Write the same test for all Transaction Name tests using Transaction Path
  • Solves Question: Naming transactions in multiple transactions scenario #361
• Swagger 2.0 / OAI support
• Transaction Paths support in external language workers/handlers
  • Adding a feature to the hook worker integration template
  • Support in all known workers (Ruby, Python, PHP, Go, Perl)
• Deprecation of all integrations to Transaction Names, introduction of Transaction Paths
  • Dredd Hooks Documentation using only Transaction Paths
  • The Transaction Object has path instead of name
  • pathOrigin instead of origin
  • Updating documentation in hook workers original repositories
  • 💀 --names, 🙌 --paths
• Moving Transaction Name logic from dredd-transactions to Dredd Reporters where it belongs

[honzajavorek]

@netmilk Just realised we also need to somehow deal with the fact that Apiary Reporting API has API Blueprint AST as part of it's contract:

...
  - blueprints (array, required) ... Array of blueprints used for the test run
      - filename (string, required) ... file name
      - raw (string, required) ... raw bleuprint content in Markdown
      - parsed (object, required)  ... parsed blueprint from raw data
        - ast (object, required) ... parsed blueprint ast
        - sourcemap (object, optional) ... sourcemap from protagonist
        - warnings (array, required) ... bleuprint parser warnings
...