Skip to content

Commit

Permalink
chore: Updated readme with Refract informations (#48)
Browse files Browse the repository at this point in the history
  • Loading branch information
pksunkara authored and kylef committed Sep 16, 2016
1 parent d96695b commit 83de6eb
Showing 1 changed file with 16 additions and 5 deletions.
21 changes: 16 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

*In nova fert animus mutatas dicere formas / corpora;*

Transforms *API Blueprint AST* or *legacy Apiary Blueprint AST* into *Apiary Application AST*.
Transforms *API Blueprint AST*, *legacy Apiary Blueprint AST* or *Refract API Description Namespace* into *Apiary Application AST*.

## Use

Expand All @@ -13,30 +13,41 @@ Really! We needed to create it for internal use within [Apiary](https://apiary.i
You ended up here for some reason though:

- Looking for [API Blueprint spec](https://github.com/apiaryio/api-blueprint/)?
- Looking for [API Elements](http://api-elements.readthedocs.io/en/latest/)
- Looking for [Apiary](https://apiary.io/)?
- Looking for [API Blueprint parser](https://github.com/apiaryio/drafter)?
- Looking for [API Description SDK](https://github.com/apiaryio/fury.js)?
- Just being curious? Well, there are probably better things to do. Have you already read today's [featured article on Wikipedia](https://en.wikipedia.org/wiki/Main_Page)?

## Purpose

Apiary supports two API description formats as of now:
Apiary supports three API description formats as of now:

#### API Blueprint - `text/vnd.apiblueprint`

- **Status:** recommended, heavily used and under active development
- **Parser:** [Drafter](https://github.com/apiaryio/drafter)
- **Parser Output:** [API Blueprint AST](https://github.com/apiaryio/api-blueprint-ast) - `application/vnd.apiblueprint.ast.raw+json` or `+yaml`
- **Parser Outputs:**
- [API Blueprint AST](https://github.com/apiaryio/api-blueprint-ast) - `application/vnd.apiblueprint.ast+json` or `+yaml`
- [API Elements](http://api-elements.readthedocs.io/en/latest/) - `application/vnd.refract.parse-result+json` or `+yaml`

#### Swagger - `application/swagger+json` or `+yaml`

- **Parser:** [fury-adapter-swagger](https://github.com/apiaryio/fury-adapter-swagger)
- **Parser Outputs:**
- [API Elements](http://api-elements.readthedocs.io/en/latest/) - `application/vnd.refract.parse-result+json` or `+yaml`

#### legacy Apiary Blueprint - `text/vnd.legacyblueprint`

- **Status:** deprecated and supported only for backward compatibility
- **Parser:** PEG.js-based [blueprint-parser](https://github.com/apiaryio/blueprint-parser)
- **Parser Output:** legacy Apiary Blueprint AST - `application/vnd.legacyblueprint.ast+json`
- **Parser Output:**
- legacy Apiary Blueprint AST - `application/vnd.legacyblueprint.ast+json`
- [API Elements](http://api-elements.readthedocs.io/en/latest/) - `application/vnd.refract.parse-result+json` or `+yaml`

To be able to work with both of these formats through some sort of uniform interface, *Apiary* internally transforms ASTs to a so-called *Application AST*. The Metamorphoses library does exactly this job, i.e. transforms any AST to the internal *Apiary Application AST*.

> **Note:** The information above is *simplified* for the context of the Metamorphoses library. As noted in the introduction, API Blueprint AST is about to be slowly replaced by [API Description Parse Result Namespace](https://github.com/refractproject/refract-spec/blob/master/namespaces/parse-result-namespace.md) as the parser output. Once [Fury](https://github.com/apiaryio/fury.js) has adapters to both *API Blueprint* and the *legacy Apiary Blueprint*, producing *API Description Parse Result Namespace* for both, and once *Apiary* starts to use the *API Description Parse Result Namespace* exclusively, this library becomes redundant.
> **Note:** The information above is *simplified* for the context of the Metamorphoses library. As noted in the introduction, API Blueprint AST is about to be slowly replaced by [API Description Parse Result Namespace](https://github.com/refractproject/refract-spec/blob/master/namespaces/api-description-namespace.md) as the parser output. Once [Fury](https://github.com/apiaryio/fury.js) has adapters to both *API Blueprint* and the *legacy Apiary Blueprint*, producing *API Description Parse Result Namespace* for both, and once *Apiary* starts to use the *API Description API Description Namespace* exclusively, this library becomes redundant.
## Interface

Expand Down

0 comments on commit 83de6eb

Please sign in to comment.