I was trying the apiblueprint to document the APIs but I am encountering an error (on line 31) that says "Dangling message-body asset, expected a pre-formatted code block, indent every of it's line by 8 spaces or 2 tabs". I started seeing this error only after I added the table of contents.
If I remove line (34) " ", then error is gone. May be I am missing something here or I may not be clear. Any help on it is appreciable. Thanks
Below is my sample markdown.
FORMAT: 1A
---
## [I. Introduction](#def-intro)
1. [Group 1](#def-g1)
1. [G1 Resource 1](#def-g1-res1)
2. [G1 Resource 2](#def-g1-res2)
2. [Group 2](#def-g2)
1. [G2 Resource 1](#def-g2-res1)
2. [G2 Resource 2](#def-g2-res2)
---
<a name="def-intro"> </a>
# I. Introduction
This is my test API
<a name="def-g1"> </a>
# 1. Group 1
This is group 1 API
<a name="def-g1-res1"> </a>
## 1. G1 Resource 1 [/g1api1]
### g1api1 [GET]
This is g1api1
+ Response 200 (application/json)
{
"response": "ok",
"resource": "g1api1"
}
<a name="def-g1-res1"> </a>
## 2. G1 Resource 2 [/g1api2]
This is g1api2
### g1api2 [GET]
+ Response 200 (application/json)
{
"response": "ok",
"resource": "g1api2"
}
One of your problems is using anchors, in particular the one right before:
2. G1 Resource 2 [/g1api2]
You don't need to do this. If you render your documentation without those anchors and look at the left hand column, you can click on the links there. You will notice the related fragment in the browser address bar. You can then just use these fragments in markdown links like:
FORMAT: 1A
# My Api
This is my test API
## Table of Contents
1. [Introduction Section](#introduction/introduction-section)
1. [Group 1](#reference/one)
1. [G1 Resource 1](#reference/one/resource-1)
2. [G1 Resource 2](#reference/one/resource-2)
## Introduction Section
Blah Blah
# Group One
This is group 1 API
## Resource 1 [/g1api1]
### g1api1 [GET]
This is g1api1
+ Response 200 (application/json)
{
"response": "ok",
"resource": "g1api1"
}
## Resource 2 [/g1api2]
This is g1api2
### g1api2 [GET]
+ Response 200 (application/json)
{
"response": "ok",
"resource": "g1api2"
}
Also, it will help you to read: https://apiary.io/blueprint
You should not be putting numbers before the "Group" and "Resource" keywords as they must come first in defining those sections. Apiary will render short-cuts in the left column for you and as I said above you can re-use the associated fragments in your own markdown links per my example above.
Related
I want to have a multi-line bit of markdown java in a yam file. I tried many things but I guess I don't quite get the quoting rules of Yaml.
{
title: Museum,
body: |
"```java
code code code
java2",
answers: [
"`museum`",
"`museum.getFloor(3)`",
"`museum.getFloor(3).getExhibit(5)`",
"`museum.getFloor(3).getExhibit(5).getCurator()`",
"`museum.getFloor(3).getExhibit(5).getCurator().name`",
"`museum.getFloor(3).getExhibit(5).getCurator().name.toUpper()`"
]
}
Produces:
/Users/pitosalas/.rbenv/versions/2.3.1/lib/ruby/2.3.0/psych.rb:377:in `parse': (generator/test.yml): found character that cannot start any token while scanning for the next token at line 3 column 9 (Psych::SyntaxError)
YAML has two styles: the JSON like flow style and the much better human readable block style.
Roughly speaking you can have nested structures each style nested within itself and can have flow style nested within block style, but block style nested within flow style is not allowed.
Your to level { and } are flow style but you try to introduce, with |, a literal block style scalar within that flow style. Replace the flow style with block style upwards from that scalar:
title: Museum
body: |
"```java
code code code
java2"
answers: [
"`museum`",
"`museum.getFloor(3)`",
"`museum.getFloor(3).getExhibit(5)`",
"`museum.getFloor(3).getExhibit(5).getCurator()`",
"`museum.getFloor(3).getExhibit(5).getCurator().name`",
"`museum.getFloor(3).getExhibit(5).getCurator().name.toUpper()`"
]
and your YAML is fine. Note that the double quotes "around" the value for the key body are not going to be stripped when loading, maybe that is not what you intended.
You should IMO not leave out the trailing , after the last value in the (flow style) sequence that is the value for answers. This will certainly lead to errors when you extend the list and forget to put in the trailing comma on the line above.
I would personally go for block style all the way:
title: Museum
body: |
"```java
code code code
java2"
answers:
- "`museum`"
- "`museum.getFloor(3)`"
- "`museum.getFloor(3).getExhibit(5)`"
- "`museum.getFloor(3).getExhibit(5).getCurator()`"
- "`museum.getFloor(3).getExhibit(5).getCurator().name`"
- "`museum.getFloor(3).getExhibit(5).getCurator().name.toUpper()`"
When dealing with YAML file generation that is convoluted or complex, or when it's not working as I expect, I revert to letting Ruby show me the way:
require 'yaml'
body = <<EOT
"```java
code code code
java2
"
EOT
answers = %w(
`museum`
`museum.getFloor(3)`
`museum.getFloor(3).getExhibit(5)`
`museum.getFloor(3).getExhibit(5).getCurator()`
`museum.getFloor(3).getExhibit(5).getCurator().name`
`museum.getFloor(3).getExhibit(5).getCurator().name.toUpper()`
)
obj = {
"title" => "Museum",
"body" => body,
"answers" => answers
}
puts obj.to_yaml
Which, in this case, outputs:
---
title: Museum
body: |
"```java
code code code
java2
"
answers:
- "`museum`"
- "`museum.getFloor(3)`"
- "`museum.getFloor(3).getExhibit(5)`"
- "`museum.getFloor(3).getExhibit(5).getCurator()`"
- "`museum.getFloor(3).getExhibit(5).getCurator().name`"
- "`museum.getFloor(3).getExhibit(5).getCurator().name.toUpper()`"
If you then pass that YAML back into the parser, you should get the original data structure back:
YAML.load(obj.to_yaml)
# => {"title"=>"Museum",
# "body"=>"\"```java\n" +
# "code code code\n" +
# "java2\n" +
# "\"\n",
# "answers"=>
# ["`museum`",
# "`museum.getFloor(3)`",
# "`museum.getFloor(3).getExhibit(5)`",
# "`museum.getFloor(3).getExhibit(5).getCurator()`",
# "`museum.getFloor(3).getExhibit(5).getCurator().name`",
# "`museum.getFloor(3).getExhibit(5).getCurator().name.toUpper()`"]}
How can I use generic named type in my API Blueprint definition?
I try like this:
FORMAT: 1A HOST: http://test.com/
# API Blueprint testing.
## Resource [/resources]
### Action [GET]
+ Response 200 (application/json)
+ Attributes
+ decorated_person (Address Decorator(Person))
# Data Structures
## Person (object)
+ first_name
+ last_name
## Address Decorator (*T*)
+ address
But Apiary Editor give me the error:
base type 'Address Decorator(Person)' is not defined in the document
here is two problems. Address Decorator isn't base type for example object and in attributes you have to use Mixin or Nesting.
FORMAT: 1A
HOST: http://test.com/
# API Blueprint testing.
## Resource [/resources]
### Action [GET]
+ Response 200 (application/json)
+ Attributes
+ Include AddressDecorator
# Data Structures
## Person (object)
+ first_name
+ last_name
## AddressDecorator (object)
+ address
I'm using Dredd to test an API I have written. It works fine until I try to vary the action uri within a resource. When I have an action of the form
## Retrieve Task [GET /task/{id}]
it sends a request to Drakov with the ] appended. This Drakov server is running the blueprint document.
Drakov 0.1.16 Listening on port 8090
[LOG] GET /task/myid]
[LOG] DELETE /task/myid]
[LOG] GET /task/myid]
You can see this request has an extra ] on the end.
This is my blueprint. It is a subset of the example from the Api Blueprint examples:
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
# Tasks [/tasks/tasks{?status,priority}]
+ Parameters
+ status `test` (string)
+ priority `1` (number)
## Retrieve Task [GET /task/{id}]
This is a state transition to another resource
+ Parameters
+ id: `myid` (string)
+ Response 200 (application/json)
{
"id": 123,
"name": "Go to gym",
"done": false,
"type": "task"
}
What am I doing wrong?
Your API Blueprint has multiple errors. For instance,
+ Parameters
+ status `test` (string)
+ priority `1` (number)
...should be:
+ Parameters
+ status: `test` (string)
+ priority: `1` (number)
Also, you are defining a resource Tasks with URI Template /tasks/tasks{?status,priority} and then you are trying to define a GET action for the resource with a different URI Template. That is confusing.
I tried to create a sample API Blueprint (saved as sample-blueprint.md) like this:
FORMAT: 1A
# My API
## Task [/task/{id}]
### Retrieve Task [GET]
+ Parameters
+ id: `123` (string)
+ Response 200 (application/json)
{
"id": 123,
"name": "Go to gym",
"done": false,
"type": "task"
}
Then I launched a Drakov server in one terminal like this:
drakov -f *.md
Then I tried to run Dredd:
dredd sample-blueprint.md http://localhost:3000
Everything passed correctly:
$ dredd sample-blueprint.md http://localhost:3000
info: Beginning Dredd testing...
pass: GET /task/123 duration: 42ms
complete: 1 passing, 0 failing, 0 errors, 0 skipped, 1 total
complete: Tests took 50ms
Is this something you originally wanted to achieve?
To illustrate my problem, I made a condensed example from the Apiary.io blueprint tutorial.
FORMAT: 1A
# Gist Fox API
# Group Gist
Gist-related resources of *Gist Fox API*.
## Gists Collection [/gists{?since}]
### List All Gists [GET]
+ Parameters
+ since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.
+ Response 200
{
items: []
}
### Create a Gist [POST]
To create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist.
+ Request (application/json)
{
"description": "Description of Gist",
"content": "String content"
}
+ Response 201
{
}
Then in my apiary documentation I get the following:
GET /gists{?since}
POST /gists{?since}
However, for me it makes sense to have the since query parameter only for the GET request. Unfortunately I didn't find a way to achieve this result:
GET /gists{?since}
POST /gists
Is it something possible?
Update
(Thursday, 23 Oct 2014)
The fix has been deployed; could you please give it a try and let me know if everything works as expected?
The bad news
It is our (Apiary) bug and you're not doing anything wrong :-(
The good news
It is a known bug we are currently working on and it is going to be fixed with the end of this week (Sunday, 19 Oct 2014) :-)
I want to search (say) "accounts" based on "name" or "status".
So I would like to have two actions :
GET /persons/?q=name==Jea*
GET /persons/?q=status==locked
How can I document that ?
I tried an Action with multiples transactions :
### GET /accounts{?q}
+ Request by name
+Parameters
+q (required, FIQLQuery)
**Only name is supported**
+ Request by status
+Parameters
+q (required, FIQLQuery)
**Only status is supported**
But Apiary editor complains because :
I must provide a message-body for my GET requests:
Message-body asset is expected to be a pre-formatted code block, every of its line indented by exactly 8 spaces or 2 tabs.
The + Parameters block is not recognized :
Ignoring unrecognized block
Thanks a lot
i can make solution that works for me.
Try this API Blueprint:
FORMAT: 1A
# requestByname
## Accounts [/accounts/?{q,type}]
### GET
+ Parameters
+ q (required, FIQLQuery)
+ type (string, `name` or `status`)
+ Request Name (application/json)
+ Response 200
{"name": "test"}
+ Request Status (application/json)
+ Response 200
{"status": 200}