According to OpenAPI specification [https://swagger.io/specification/] I can define the minimum and maximum values of the field in the schema object properties.
But actually Google endpoint does not perform any validation
My Swagger file fragment:
parameters:
- name: message
in: body
description: sug
schema:
required:
- Message
properties:
Message:
type: integer
minimum: 1
maximum: 1
MessageId:
When I send a wrong request:
curl https://xxxxxxxxxxxxxxxxxxxxd"Message=10&MessageId=456789123456&TimeStamp=20190611101010212&OperatorId=15&GlobalAccountId=81165751216851320000&Reason=3"
The Endpoint does not reject the request, but invokes the cloud function.
You are correct. Google Cloud Endpoints doesn't do any OpenAPI object property validation.
Related
I have a bunch of API endpoints that return text/csv content in their responses. How do I document this? Here is what I currently have:
/my_endpoint:
get:
description: Returns CSV content
parameters:
- $ref: '#/components/parameters/myParemeters'
responses:
200:
headers:
$ref: '#/components/headers/myHeaders'
content: text/csv
As it stands, this does not work and I get the note in the Swagger preview:
Could not render this component, see the console.
The question is how do I properly display the content for csv responses? I find if does work if I do add a schema, something like this:
...
content:
text/csv:
schema:
type: array
items:
type: string
...
But there shouldn't be a schema since it is csv. So to go back to the question, what is the proper way to describe the csv response content?
Your first example is not valid syntax. Replace with:
responses:
'200':
content:
text/csv: {} # <-----
# Also note the correct syntax for referencing response headers:
headers:
Http-Header-Name: # e.g. X-RateLimit-Remaining
$ref: '#/components/headers/myHeader'
components:
headers:
myHeader:
description: Description of this response header
schema:
type: string
As for your second example, OpenAPI Specification does not provide examples of CSV responses. So the schema could be type: string, or an array of strings, or an empty schema {} (this means "any value"), or something else. The actual supported syntax might be tool-dependent. Feel free to ask for clarifications in the OpenAPI Specification repository.
Here is another worked one for openapi 3.0.2 to return text/csv content (string) from backend:
Contract:
responses:
'200':
content:
text/csv:
schema:
type: string
Backend:
return ResponseEntity.ok("h1,h2,h3,h4\n1,2,3,4\n5,6,7,8");
Here is one more example:
Contract:
responses:
'200':
schema:
type: object
Backend:
return ResponseEntity.status(200).contentType(MediaType.parseMediaType("text/csv")).body("Col 1;Col2\naaa;bbb\nccc;ddd");
I'm seeking the best way for documenting my rest API response according to JSON API and also how to describe it in Swagger YAML documentation.
My API receives a word and a list of URLs and returns how many times the given word appears in each website provided. My first take for the successful response was:
{
"data": {
"foo": {
"http://www.foobar.com": 12,
"http://www.bar.com": 0
}
}
}
Using the word and the URLs as property names.
I'd like to know if it is a good practice according to JSON API and if yes, how to document it in Swagger YAML:
swagger: '2.0'
info:
description: How many times a given word appears in each site provided? This API answer it
version: 1.0.0
title: WordApp
contact:
email: foo#bar.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
paths:
/:
get:
summary: returns how many times a given word appears in each provided URL
description: |
By passing in the appropriate options, you can search for
the number of occurrences of a given word in each URL provided
produces:
- application/json
parameters:
- in: query
name: word
description: pass a word for looking up its occurrences in each site
required: true
type: string
- in: query
name: url
description: a list of valid URLs
type: string
required: true
responses:
200:
description: search results matching criteria
schema:
type: array
items:
$ref: '#/definitions/Data'
500:
description: Internal Server Error
definitions:
Data:
type: object
required:
- word
- url
- value
properties:
word:
type: string
example: Brazil
url:
type: string
example: 'https://www.nytimes.com/'
value:
type: integer
example: 12
If it is not the best practice, what would be a better way of modeling my response?
I am doing the following steps to convert an .rvt file into .svf
Authenticate
upload .rvt file
translate it to .svf (with modelderivative/v2/designdata/job)
with the response check the job complete by checking the manifest (/modelderivative/v2/designdata/{urn}/manifest)
once the job is complete (from manifest status), the response I get does not contain derivatives urns
Link to the complete manifest response : https://drive.google.com/file/d/0ByrHSB-f7jP3TXhHYVQtOEUyM2c/view?usp=sharing
Sample response: the derivative urn is missing
class ManifestDerivative {
name: autodesk.rvt
hasThumbnail: true
outputType: svf
progress: complete
status: success
children: [class ManifestChildren {
type: geometry
role: 2d
name: 03.51 - Detail V.01
hasThumbnail: true
mime: null
urn: null
progress: complete
status: success
resolution: []
modelGUID: null
objectIds: []
messages: null
}, class ManifestChildren {
type: geometry
role: 2
....
I want to know whether the urn returned by this response manifest is enough for downloading the bubble or there is something that I am doing wrong
The manifest is enough to download svf, however it is not a straightforward workflow, take a look at my recent blog post: Forge SVF Extractor in Node.js and at this project that does the extraction for you: https://extract.autodesk.io. You can find the source there.
How do I define a JSON object value for a request parameter that is in: query (not in: body)?
Example below:
paths:
/schedules:
get:
summary: Gets the list of schedules
description: |
The schedules endpoint returns information about the configured schedules.
parameters:
- name: filter
in: query
description: >
Returns whether alert runs on matching schedule.
Example request:
{
"type": "a",
"start" : "b",
"stop" : "c"
}
required: true
type: string
Because it's not in: body, I cannot use schema.
I have a RESTful API that I have created recently and I won't remember how to use it in a few months. I decided to document my API using Swagger, however I'm going crazy.
I used http://editor.swagger.io/ to create the YAML file that I then convert into a JSON file Swagger can use. When I put file into Swagger UI it just gets stuck at fetching resource list: localhost/swagger.json and the console says Uncaught TypeError: Cannot read property '$ref' of undefined .
I'm using version 2.1.0-alpha.5 of Swagger UI.
Here is my spec file:
swagger: '2.0'
info:
title: TITLE
description: BLAH, BLAH, BLAH, ETC
version: "1.0b"
host: api.example.com
schemes:
- http
basePath: /v1
produces:
- application/json
paths:
/match.json:
get:
#summary: Match Data
description: Used for getting data about a match
parameters:
- name: id
in: query
description: The match ID of from a game
required: true
type: integer
format: int32
- name: key
in: query
description: API key used for authentication.
required: true
type: string
responses:
200:
description: Returns match data
schema:
type: array
items:
$ref: '#/definitions/MatchData'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
definitions:
MatchData:
properties:
info:
type: integer
format: int64
description: General information about the match
time:
type: integer
format: int64
description: Information about the start/end time
stats:
type: array
format: int64
description: Stats about the match
Error:
required:
- errorID
- message
properties:
errorID:
type: string
description: Error ID.
message:
type: string
description: Information about the error.
I've tested your spec, and while I'm not getting the same error you do, the spec is indeed invalid.
If you look at #/definitions/MatchData/properties/stats, you'll see that you define the type: array but you don't provide an 'items' property next to it to say which array it is (and that's mandatory). You may have intended to use type: integer like the properties above it, which goes along with the format: int64.
Since I don't know what you intended to provide, it's difficult to give an accurate solution, but if you add a comment with what you intended to do, I could provide a more detailed answer.
Upon some additional testing, I discovered that there's a bug in the UI. After you make that modification and the spec loads, the operation itself will not expand unless you click on the Expand Operations link. I've opened an issue about it, feel free to follow it there.
This problem can be due to some indentation errors in the yaml file which actually did not show up in the Swagger editor. Check all your definitions and whether they are getting displayed as expected in the preview that you can see in Swagger editor (especially check MatchData).
You can also try giving:
responses:
200:
description: Returns match data
schema:
type: array
items:
schema:
$ref: '#/definitions/MatchData'
For our case, we used Swagger-php and we have:
* #SWG\Response(
* response=200,
* description="app response"
* #SWG\Schema(
* type="array"
* )
* ),
but we missed " * #SWG\Items(ref="#/definitions/pet")". After removing "#SWG\Schema(", it works e.g.
* #SWG\Response(
* response=200,
* description="app response"
* ),