Open jmdacruz opened 9 years ago
This is something we have been thinking about but the MSON feature is still in beta and we would like to finish supporting it first.
Sounds good! Just wanted to get it on your radar.
I think it will become an important feature over time, as people start using Apiary for emulating different sample outputs using the "Prefer" header (which I think it's a very powerful feature). Developers using the "Prefer" header in combination with complex (e.g., nested) objects won't be able to use MSON because of the limitation I've documented in this issue (the alternative would be having different Named Types for each sample, which defeats the purpose of using MSON)
or that are somehow validated against the type definition (in order to avoid inconsistencies between samples and the type definition)
This is definitely planned for a future release of the parser.
As for the referencing one sample from another – I do not really see a use as for it. Maybe an example would help?
Note, in MSON, there is nothing like type definition and instantiation – those two are essentially a the same.
Isn't something like:
# Data Structures
## A (object)
+ a1: 1
+ a2: 2
# Resource A [/a]
## Create [GET]
+ request (application/json)
+ attributes (A)
+ response 201
+ request (application/json)
+ attributes (A)
+ a2: 42
+ response 400
working for you?
Note this is related to https://github.com/apiaryio/api-blueprint/issues/58 (when it comes to specifying what is a response based on input properties)
I see... so you basically try to instantiate the attributes at the Resource
, when you are instantiating the data structure. I tried with the blueprint below, but it's not working for me (let me know if there is something wrong with it...)
FORMAT: 1A
HOST: http://parametrizedmson.apiblueprint.org/
# Testing parametrized MSON
Just testing parametrized MSON.
# Resource A [/a]
## Create [GET]
+ request (application/json)
+ attributes (A)
+ response 201
+ request (application/json)
+ attributes (A)
+ a2: 42
+ response 400
# Data Structures
## A (object)
+ a1: 1
+ a2: 2
Comments and questions:
400
response you'll get a parameter table with 3 parameters instead of two (with a2
having a value of 42). This is what I get:Name | Type | Required | Description | Value |
---|---|---|---|---|
a2 | optional | 42 | ||
a1 | optional | 1 | ||
a2 | optional | 2 |
response 400
to show just one instance of a2
with a2 => 42
, and also that the example POST payload shows 42
as the value for a2
Data Structure A
had a nested reference to a Data Structure B
defined separately? What I'd like to do with this you propose is to be able to parametrize attributes on the Request
section that would affect both Data Structure A
and Data Structure B
A
is an item and B
includes a collection of A
s:# Data Structures
## Item (object)
### Properties
- uuid: `08ff7052-2e95-11e3-a1fc-000c294eede0` (required, string, sample) - A unique ID
- property1: 42
- property2: 56
## Collection (object)
### Properties
- data (object, required, sample)
- currentItemCount: `1` (required, number, sample) - Number of items in the current view of the collection
- totalItems: `1` (required, number, sample) - Number of total items in the collection
- items (array[Item])
Collection
where I can define different values for the Item
values in the array?
Hey @jmdacruz
Regarding the a: 42
not overriding the a: 2
, it is an known bug and we are working on it. But other than, your 2 other feature requests are good and we will be looking into them. Thanks.
Great to now! Thanks!
@pksunkara is there a tracking issue for the "a: 42 not overriding the a: 2" ?
hmm... Looks like we don't have a tracking issue for it.
@pksunkara so please create one or turn this one into it (but preferably the former and on the parser). Thanks!
If we do not have a tracking issue then it is not a know issue :)
thanks @pksunkara
Just to reiterate. Is there another issue but the fix of https://github.com/apiaryio/drafter/issues/44 .
@jmdacruz are we looking for a way to display different samples in libraries using MSON or are we asking parser – representation renderer to render specific sample instead of the default one?
From what I understood, @jmdacruz was talking about having a way to select a specific sample to be sent the to the renderer in certain cases instead of the default one.
Example (disregard the syntax): We have a named type User
with samples describing users pavan
and kyle
.
+ (array)
+ (User:pavan)
+ (User:kyle)
should render the following:
[
{
"username": "pavan"
},
{
"username": "kyle"
}
]
@zdne can you elaborate on the difference between these two alternatives?
are we looking for a way to display different samples in libraries using MSON or are we asking parser – representation renderer to render specific sample instead of the default one?
I recently found myself in the following situation: I defined a couple of Named Type objects, one referencing the other(e.g., object A has a reference to object B). Each of the objects may have a couple of Sample sections. I'd like to have the ability, when defining the Sample section of object A, to reference a particular Sample in object B's definition. This would allow me to document difference scenarios of the API.
Moreover, I'd like to see Samples that are just instantiations of the type definitions, or that are somehow validated against the type definition (in order to avoid inconsistencies between samples and the type definition)