Adds API Blueprint #313
Adds API Blueprint #313
Conversation
|
Don't be scared with the |
kurko
force-pushed
the
235-blueprint-api
branch
2 times, most recently
from
683874e to
33a6dcb
Compare
|
A few issues when trying this out in my project (will keep this list up to date as I go):
|
* `parameter :id, required: true` renders `id: (required, ) - id` * `parameter :id, required: false` renders `id: () - id` Connects to #313
This commit adds API Blueprint (APIB) to this gem. A few highlights:
* APIB groups entities, resources, routes, HTTP verbs and requests
differently than what the gem currently uses. Because of that I had to
override more methods than usual in the `Markup` classes.
APIB has the following structure:
1. resource (e.g "Group Orders")
2. route (e.g "Orders Collection [/orders]")
3. HTTP method (e.g "Loads all orders [GET]")
4. Requests. Here, we show all different requests which means that
we don't have the repetition of GET for each example. All
examples stay under one, unified HTTP method header.
* APIB differentiates parameters (values used in the URLs) from
attributes (values used in the actual request body). You can use
`attributes` in your texts.
* APIB has a `route` header, which means we had to add a new RSpec block
called `route()` which wraps HTTP methods, like the following:
```ruby
route "/orders", "Orders Collection" do
get "Returns all orders" do
# ...
end
delete "Deletes all orders" do
# ...
end
end
```
If you don't use `route`, then param in `get(param)` should be an URL.
* APIB is not navigable like HTML, so generating an index file makes no
sense. Because of that, we are generating just one file, `index.apib`.
* We are omitting some APIB features in this version so we can get up
and running sooner. Examples are object grouping, arrays objects and a
few description points.
Unrelated to APIB:
* FakeFS was being used _globally_ in test mode, which means that
nothing would load file systems, not even a simple `~/.pry_history`, which
made debugging impossible. I moved the usage of this gem to the places
where it is used.
Closes #235.
* `parameter :id, required: true` renders `id: (required, ) - id` * `parameter :id, required: false` renders `id: () - id` Connects to #313
This allows for routes to be defined with optional querystrings, like:
```ruby
route '/orders/:id{?optional=:optional}', "Single Order" do
```
Before this, the http methods (e.g `get`, `post`) were injecting the
optional into the final URI. This moves optionals into another metadata
key (`options[:route_optionals]`).
JSON requests should use UTF-8 by default according to http://www.ietf.org/rfc/rfc4627.txt, so we will remove `charset=utf-8` when we find it to avoid redundancy. In the process, I moved code that was only used by APIB into the APIB classes, such as exposing `content_type` to the templates. If I changed the `content-type` for all templates it would break unrelated things. Connects to #235.
kurko
force-pushed
the
235-blueprint-api
branch
from
e601e5f to
eb8db63
Compare
|
Extra bugs:
|
|
This would be a great feature @kurko ! Is it still in progress? |
|
@jmcarp I've been developing with it in the past 2 months here and it's working great. As I need more features, I realize I missed a few things here and there, for example the last checklist above (about |
|
Can't wait to see it live ! Do you have an ETA ? ❤️ |
|
No ETA just yet, @terry90. We're using it internally in a multiple systems. We want to have it close to 100% when we merge it. As noted above in my last comment, EDIT: if anyone would like to help with the |
|
@oestrich I think we're good to merge this one. We're using this in 7+ apps here and it's working pretty good so far cc @jakehow Re: the 2 items at #313 (comment), I'll create a separate issue because they're not really bugs, just missing features. |
|
@oestrich let me know if any concerns on getting this merged. We are using this successfully and I am 👍 on the PR from a code review standpoint. |
|
My only concern is adding a DSL specific to a format that anything can use, but it's not a big one. Merging. Thanks for the PR @kurko |
|
5.0.0 is out including this. |
|
@oestrich fantastic. About the DSL, I share you concern. APIB has a different format, though, that requires some specific inputs. We just need to keep an eye to not grow beyond this. Perhaps it'd be a good idea to have adapters (via composition), not just inheritance, so we can extend beyond these formats without changing the core DSL. Thanks for merging. |
This commit adds API Blueprint (APIB) to this gem. A few highlights:
APIB groups entities, resources, routes, HTTP verbs and requests
differently than what the gem currently uses. Because of that I had to
override more methods than usual in the
Markupclasses.APIB has the following structure:
we don't have the repetition of GET for each example. All
examples stay under one, unified HTTP method header.
APIB differentiates parameters (values used in the URLs) from
attributes (values used in the actual request body). You can use
attributesin your texts.APIB has a
routeheader, which means we had to add a new RSpec blockcalled
route()which wraps HTTP methods, like the following:If you don't use
route, then param inget(param)should be an URL.APIB is not navigable like HTML, so generating an index file makes no
sense. Because of that, we are generating just one file,
index.apib.We are omitting some APIB features in this version so we can get up
and running sooner. Examples are object grouping, arrays objects and a
few description points.
Unrelated to APIB:
nothing would load file systems, not even a simple
~/.pry_history, whichmade debugging impossible. I moved the usage of this gem to the places
where it is used.
Closes #235.