-
Notifications
You must be signed in to change notification settings - Fork 180
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Repeating a data structure with different values #94
Comments
I've updated my question with better examples. |
The reason they are strings and not numbers is because the default type is string and the value isn't set as a number type. If you change the following they will become numbers:
|
Right - that's what I thought MSON would handle (since |
... So the benefit of using a data structure in this case is nill? I hope I'm not coming across as sour on this. I'm just genuinely trying to understand if there is a benefit to using a data structure in this case. API Blueprint is pretty awesome! |
In a larger API, MSON gives you a way to reuse a data structure. Given perhaps a CRUD version of a restaurant API you could do something like the following: # Restaurant API
## Restaurants Collection [/restaurants]
### List all restaurants [GET]
+ Response 200 (application/json)
+ Attributes (array[Restaurant], fixed-type)
### Create a Restaurant [POST]
+ Request (application/json)
+ Attributes (Restaurant)
+ Response 200 (application/json)
+ Attributes (Restaurant)
## Restaurant [/restaurants/{id}]
+ Parameters
+ id: 1 (number)
### View [GET]
+ Response 200 (application/json)
+ Attributes (Restaurant)
### Update [PATCH]
+ Request (application/json)
+ Attributes (Restaurant)
+ Response 200 (application/json)
+ Attributes (Restaurant)
### Delete [DELETE]
+ Response 204
# Data Structures
## Restaurant
+ `restaurant_name`: McDonald's (string, required) - The name of this restaurant
+ `years_of_operation`: 54 (number, required) - The number of years since established In your particular use-case I agree with you that how MSON works doesn't quite work well for that particular case. If you wanted to perhaps copy a real world response for an example over you could also do something like the following where I've included an actual JSON body alongside the attributes. As another option. ### List all restaurants [GET]
+ Response 200 (application/json)
+ Attributes (array[Restaurant], fixed-type)
+ Body
[
{ "restaurant_name": "x", "years_of_operation": 5 },
{ "restaurant_name": "y", "years_of_operation": 6 },
{ "restaurant_name": "z", "years_of_operation": 5 }
] In terms of rendering in Apiary documentation, it will then only keep 1 example which may be desired to keep the attributes section small and compact and just including the base structures (and not any larger examples): While the JSON example, and the mock server would show the included example: |
Hmmm, that last half is helpful. Thank you so much Kyle! |
Looks like you have to declare the sample data for each member of the array; it doesn't give defaults:
|
I have many places in my API where I will need to describe a list of objects. Each object has the same keys / structure but different values. How can I tweak the values of each instance of some data structure while retaining all the original type, description, etc of the original structure?
for example if I had the following data structure
Restaurant
Then, let's say I want to instantiate several
Restaurants
in a GET response like so:the JSON body would look like this (note how
years_of_operation
for Bob Evans and Eatly are now numbers)and the rendered documentation will only show this (the descriptions for
restaurant_name
andyears_of_operation
for Bob Evans and Eatly are now missing)I thought that MSON would carry over those descriptions and type definitions. Otherwise, I have to update a description (or type, requirement, etc) everywhere that data structure is used... but I was under the impression this is a sort of problem MSON is supposed to solve? Am I doing something silly?
The text was updated successfully, but these errors were encountered: