From 828fc7a19ba7dbf36da48aa3b02486c6c9a6a4cd Mon Sep 17 00:00:00 2001 From: "Daniel G. Taylor" Date: Tue, 28 Apr 2015 22:21:30 -0700 Subject: [PATCH] Add support for API Blueprint This adds a grammar and samples for [API Blueprint][] based on the [Sublime Text plugin][] from Apiary. The [Atom language][] is also based on the Sublime plugin. API Blueprint is now used in over [3,600 repositories][] on GitHub and has [several][Aglio] [open source][Dredd] [tools][Drakov] available. Here's an [example using Lightshow][Lightshow] to highlight a small API. [3,600 repositories]: https://github.com/search?utf8=%E2%9C%93&q=FORMAT+1A+extension%3Aapib+extension%3Amd&type=Code&ref=advsearch&l= [Aglio]: https://github.com/danielgtaylor/aglio [API Blueprint]: https://apiblueprint.org/ [Drakov]: https://www.npmjs.com/package/drakov [Atom language]: https://github.com/danielgtaylor/atom-language-api-blueprint [Dredd]: https://github.com/apiaryio/dredd [Lightshow]: https://github-lightshow.herokuapp.com/?utf8=%E2%9C%93&scope=from-url&grammar_url=https%3A%2F%2Fgithub.com%2Fapiaryio%2Fapi-blueprint-sublime-plugin%2Fblob%2Fmaster%2FAPIBlueprint.tmLanguage&grammar_text=&code_source=from-url&code_url=https%3A%2F%2Fraw.githubusercontent.com%2Fapiaryio%2Fapi-blueprint%2Fmaster%2Fexamples%2F12.%2520Advanced%2520Action.md&code= [Sublime Text plugin]: https://github.com/apiaryio/api-blueprint-sublime-plugin --- .gitmodules | 3 ++ grammars.yml | 3 ++ lib/linguist/languages.yml | 8 +++ samples/API Blueprint/actions.apib | 55 ++++++++++++++++++++ samples/API Blueprint/attributes.apib | 39 ++++++++++++++ samples/API Blueprint/simple.apib | 18 +++++++ vendor/grammars/api-blueprint-sublime-plugin | 1 + 7 files changed, 127 insertions(+) create mode 100644 samples/API Blueprint/actions.apib create mode 100644 samples/API Blueprint/attributes.apib create mode 100644 samples/API Blueprint/simple.apib create mode 160000 vendor/grammars/api-blueprint-sublime-plugin diff --git a/.gitmodules b/.gitmodules index f1ce5891..be0e86cb 100644 --- a/.gitmodules +++ b/.gitmodules @@ -657,3 +657,6 @@ [submodule "vendor/grammars/jflex.tmbundle"] path = vendor/grammars/jflex.tmbundle url = https://github.com/jflex-de/jflex.tmbundle.git +[submodule "vendor/grammars/api-blueprint-sublime-plugin"] + path = vendor/grammars/api-blueprint-sublime-plugin + url = https://github.com/apiaryio/api-blueprint-sublime-plugin diff --git a/grammars.yml b/grammars.yml index 46f2fd5d..d34253ac 100644 --- a/grammars.yml +++ b/grammars.yml @@ -156,6 +156,9 @@ vendor/grammars/antlr.tmbundle: vendor/grammars/apache.tmbundle: - source.apache-config - source.apache-config.mod_perl +vendor/grammars/api-blueprint-sublime-plugin/: +- text.html.markdown.source.gfm.apib +- text.html.markdown.source.gfm.mson vendor/grammars/applescript.tmbundle: - source.applescript vendor/grammars/asciidoc.tmbundle/: diff --git a/lib/linguist/languages.yml b/lib/linguist/languages.yml index 662c488f..da046cae 100644 --- a/lib/linguist/languages.yml +++ b/lib/linguist/languages.yml @@ -59,6 +59,14 @@ ANTLR: - .g4 ace_mode: text +API Blueprint: + type: markup + color: "#2ACCA8" + ace_mode: markdown + extensions: + - .apib + tm_scope: text.html.markdown.source.gfm.apib + APL: type: programming color: "#5A8164" diff --git a/samples/API Blueprint/actions.apib b/samples/API Blueprint/actions.apib new file mode 100644 index 00000000..f94dc67a --- /dev/null +++ b/samples/API Blueprint/actions.apib @@ -0,0 +1,55 @@ +FORMAT: 1A + +# Advanced Action API +A resource action is – in fact – a state transition. This API example demonstrates an action - state transition - to another resource. + +## API Blueprint ++ [Previous: Resource Model](11.%20Resource%20Model.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/11.%20Advanced%20Action.md) + +# Tasks [/tasks/tasks{?status,priority}] + ++ Parameters + + status (string) + + priority (number) + +## List All Tasks [GET] + ++ Response 200 (application/json) + + [ + { + "id": 123, + "name": "Exercise in gym", + "done": false, + "type": "task" + }, + { + "id": 124, + "name": "Shop for groceries", + "done": true, + "type": "task" + } + ] + +## Retrieve Task [GET /task/{id}] +This is a state transition to another resource + ++ Parameters + + id (string) + ++ Response 200 (application/json) + + { + "id": 123, + "name": "Go to gym", + "done": false, + "type": "task" + } + +## Delete Task [DELETE /task/{id}] + ++ Parameters + + id (string) + ++ Response 204 diff --git a/samples/API Blueprint/attributes.apib b/samples/API Blueprint/attributes.apib new file mode 100644 index 00000000..ce143f7b --- /dev/null +++ b/samples/API Blueprint/attributes.apib @@ -0,0 +1,39 @@ +FORMAT: 1A + +# Attributes API +This API example demonstrates how to describe body attributes of a request or response message. + +In this case, the description is complementary (and duplicate!) to the provided JSON example in the body section. The [Advanced Attributes](09.%20Advanced%20Attributes.md) API example will demonstrate how to avoid duplicates and how to reuse attributes descriptions. + +## API Blueprint ++ [Previous: Parameters](07.%20Parameters.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/08.%20Attributes.md) ++ [Next: Advanced Attributes](09.%20Advanced%20Attributes.md) + +# Group Coupons + +## Coupon [/coupons/{id}] +A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. + +### Retrieve a Coupon [GET] +Retrieves the coupon with the given ID. + ++ Response 200 (application/json) + + + Attributes (object) + + id: 250FF (string) + + created: 1415203908 (number) - Time stamp + + percent_off: 25 (number) + + A positive integer between 1 and 100 that represents the discount the coupon will apply. + + + redeem_by (number) - Date after which the coupon can no longer be redeemed + + + Body + + { + "id": "250FF", + "created": 1415203908, + "percent_off": 25, + "redeem_by:" null + } diff --git a/samples/API Blueprint/simple.apib b/samples/API Blueprint/simple.apib new file mode 100644 index 00000000..ecee8481 --- /dev/null +++ b/samples/API Blueprint/simple.apib @@ -0,0 +1,18 @@ +FORMAT: 1A + +# The Simplest API +This is one of the simplest APIs written in the **API Blueprint**. +One plain resource combined with a method and that's it! We will explain what is going on in the next installment - [Resource and Actions](02.%20Resource%20and%20Actions.md). + +**Note:** As we progress through the examples, do not also forget to view the [Raw](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md) code to see what is really going on in the API Blueprint, as opposed to just seeing the output of the Github Markdown parser. + +Also please keep in mind that every single example in this course is a **real API Blueprint** and as such you can **parse** it with the [API Blueprint parser](https://github.com/apiaryio/drafter) or one of its [bindings](https://github.com/apiaryio/drafter#bindings). + +## API Blueprint ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md) ++ [Next: Resource and Actions](02.%20Resource%20and%20Actions.md) + +# GET /message ++ Response 200 (text/plain) + + Hello World! diff --git a/vendor/grammars/api-blueprint-sublime-plugin b/vendor/grammars/api-blueprint-sublime-plugin new file mode 160000 index 00000000..4713b0e8 --- /dev/null +++ b/vendor/grammars/api-blueprint-sublime-plugin @@ -0,0 +1 @@ +Subproject commit 4713b0e8248b63d993ec5bcaf3d70051e56acec2