I am using grape-swagger to show documentation on my Ruby API i'm building using Grape.
I am adding descriptions to all of my parameters on my endpoints but I can't seem to find anything about how to add descriptions to route parameters.
I have tried the following:
route_param :monitor_name, type: String, desc: 'The name of the monitor that is being retrieved.' do
and
route_param :monitor_name, type: String, description: 'The name of the monitor that is being retrieved.' do
but neither of those will display the actual description on the swagger UI.
Any ideas?
Thanks for the help!
p.s. (the only thing I found in the grape documentation is shown in the attach image)
You could use
route_param :monitor_name, type: String, documentation: { desc:'The name of the monitor that is being retrieved.' }
Related
I am a little confused by Swagger's enum support for OpenAPI3.0. My point here being that there have been new improvements in swagger doc where there is support for re-usable enums as
documented here:
https://swagger.io/docs/specification/data-models/enums/
where support for reusable enums is stated using $ref. However, when I post my swagger.json to swagger editor/validator which looks like following
in: query
name: prop-name
description: something
type: array
items:
$ref: '#/definitions/mytype'
which is further defined below:
mytype:
enum:
- Item1
type: string
Swagger editor throws an error and says should NOT have additional properties
additionalProperty: $ref
Now, this is not a problem when loading the swagger page and attaining the functionality but it is an issue when it comes to using swagger-gen and generating clients using it. the swagger-gen CLI also throws the same error causing us to now being able to generate a client for this page correctly.
Is there anything wrong with this swagger.json? I there any extra information that I can provide to shed light on this issue?
In OpenAPI 2.0, array parameter schemas cannot use $ref. You must define the enum inline:
- in: query
name: prop-name
description: something
type: array
items:
type: string
enum:
- Item1
This seems like a basic question, but I'm well into my second day now :(
I'm using the Google Drive Ruby Api here: https://github.com/google/google-api-ruby-client but the basic file examples in the README appear to be well out of date. In particular, calls to Drive.update_file don't take anything like the parameters shown.
So far, I can get hold of an authorized DriveService:
drive = Google::Apis::DriveV3::DriveService.new
drive.authorization = Google::Auth.get_application_default(['https://www.googleapis.com/auth/drive'])
I can get a File:
file_id = 'string-of-stuff'
file = drive.get_file file_id
I can set attributes on the File object that look okay:
file.update!(name: 'My new name')
But, I can't figure out how to get the update/patch to actually work after that. The README suggests drive.update_file(file), but that just explodes with a type error.
TypeError: Can't convert Google::Apis::DriveV3::File into String or Array.
Looking at the code, #update_file actually expects a file_id as the first param.
I've tried all sorts of variations based on the README, like:
drive.update_file(file_id, {name: 'New name'})
or:
drive.update_file(file_id, {title: 'New name'})
or (looking at the code):
drive.update_file(file_id, fields: {title: 'New name'})
or even:
drive.update_file(file_id, file)
which explodes with:
Google::Apis::ClientError: fieldNotWritable: The resource body includes fields which are not directly writable.
But nothing works for me. Has anyone used this library? Everything else seems fairly straightforward, but this is just HARD.
Well, after much more trial-and-error, the ONLY way this API works is with a new File object. If you use get_file to get your File, then you end up with an object that has an unwritable id field.
So, this - and only this - appears to work:
drive.update_file(file_id, Google::Apis::DriveV3::File.new(name: name))
Sigh.
Just verified that the following works:
drive.update_file(file_id, { name: new_name })
You no longer need to create a new File object to update the name of an existing file.
I'm trying to using Koala gem to search for facebook page, like this
#graph.get_connection('search', movie_name)
but I got this /Users/luizeduardo/.rbenv/versions/2.2.3/lib/ruby/2.2.0/uri/generic.rb:1100:in rescue in merge': bad URI(is not URI?): /search/Jurassic World (URI::InvalidURIError)
Seems like I'm using the wrong method OR this is not possible
Have a look at
https://github.com/arsduo/koala/wiki/Graph-API#getting-private-data
You can also search for users/pages/events/groups for the keyword of your choice:
# http://graph.facebook.com/search?q=koala&type=place
#graph.get_connection('search', type: :place)
# => [{"category"=>"Attractions/things to do", ...
# "name"=>"Maru Koala & Animal Park"}]}
In your case this would mean
#graph.get_connection('search', type: :page)
IMHO...
See
https://developers.facebook.com/docs/graph-api/using-graph-api/v2.4#search
get_connection throws the same error for me as well (maybe because v2.6?).
anyway, i found that solution works:
#graph.get_object('search?q=YOUR_QUERY&type=page')
You're use of get_connection seems like the incorrect method for doing a general search of public page data. get_connection has more to do with FB friends network. For a more detailed understanding of what API calls Koala will make, have a look at the code which has good comments describing how each method works. For general API graph calls you can simply use the graph_call method.
https://github.com/arsduo/koala/blob/master/lib/koala/api/graph_api.rb
You should be able to use the graph_call method and pass in whatever api call you'd like to make as single parameter in a string.
fb = Koala::Facebook::API.new(ENV['FACEBOOK_CLIENT_TOKEN'])
lookup = fb.graph_call("search?q=star%20wars%20movie&type=page")
see similar question and answer here
The Koala Wiki should say this:
#graph.search('koala', type: :place)
instead of this:
#graph.get_connection('search', type: :place)
Hopefully that gets you closer to a solution.
I'm trying to model a GET request in my RAML that has an arbitrary list of URL parameters. 2 parameters are known, but the remainder are name/value pairs that are chosen from the response data from other request types. I tried to use additionalParameters: true in my queryParameters list, but I get an error message from osprey-mock-service when it attempts to parse the RAML:
each query parameter must be a map
The relevant snippet from my RAML is:
/statistics:
/{statisticId}:
get:
description: Get the stastic data
queryParameters:
start:
displayName: Start Time
type: integer
description: The timstamp in milliseconds indicating the beginning of the collection of timeseries data
example: 1380601800000
required: false
end:
displayName: End Time
type: integer
description: The timstamp in milliseconds indicating the end of the collection of timeseries data
example: 1380601800000
required: false
additionalParameters: true
responses:
200:
body:
application/json:
schema: statistic
example: !include ../dto/statistic.sample
The error message goes away when I remove the line:
additionalParameters: true
I have not found a reference that indicates that you can use additionalParameters with queryParameters, but it seems to make sense that you could.
I don't necessarily need to resolve the error message, but I would like to have URL parameters like the following:
?start=23010030&end=23011470&content=abc.com&node=siteA
Where content and node are not predefined parameter names.
Is this possible?
additionalParameters is currently not supported by RAML: it is nowhere to be found in version 0.8 of the specification.
This said, this (very important) topic is under discussion in the RAML forums
So for the moment, I see only two options:
Do not specify these parameters, the caveat being that tools, like RAML Tester, will report request violations if you use these parameters.
Specify all the possible parameters with required: false, the caveat being that you need to know all these parameters beforehand.
I'm writing some RAML in an API designer and I have the following code:
/users:
/{id}:
/tags:
description: Personal tags of a user
get:
description: A list of the user's personal tags
responses:
200:
body:
application/json:
example: |
{
tags: [
{...},
...
]
}
/{slug}:
description: A personal tag
put:
The parser is throwing an error at /{slug} because it thinks that I'm trying to use it as a property of the get: method. However, /{slug} needs to be indented to make it subordinate to /tags.
Is there a way in RAML (or YAML, since RAML is supposed to be an instance of YAML), to mark the end of a map? Or do you have any other suggestions?
RAML doesn't (AFAIK) support explicit termination of maps, but we also don't need that to solve your problem :-).
Since in YAML the whitespace is semantic, what's happening is that your GET method is currently indented such that it's a method on the /users/{id} level, so even though it looks like /{slug} is subordinate to tags, it thinks it is in the definition of /users/{id} Really, we should probably throw an error here, since the method definition comes after you've defined a sub-resource (thanks for finding this case).
To solve, all you need to do is indent your description and get definition for /users/{id}/tags one additional level, and it should all parse fine. Updated RAML is below.
/users:
/{id}:
/tags:
description: Personal tags of a user
get:
description: A list of the user's personal tags
responses:
200:
body:
application/json:
example: |
{
tags: [
{...},
...
]
}
/{slug}:
description: A personal tag
put: