Is it possible to render inline images as part of description texts etc in openapi3.0/swagger?
When looking at the spec, all I can find is the ability to link to images in request examples, specifically. What I want is to be able to include diagrams etc in introductory texts of my API, similar to markdown etc. Example:
openapi: 3.0.2
info:
version: "1.0.0"
title: "My API"
description: "This API bla bla bla [block diagram] bla bla [another inline image]"
Is anything like this at all possible?
At least with the ReDoc renderer, it seems possible to use HTML straight into your description texts, so adding <img src="./image.png" /> appears to work:
openapi: 3.0.2
info:
version: "1.0.0"
title: "My API"
description: "This API bla bla bla <img src="./block-diagram.png" /> bla bla <img src="./another-inline-image.png" />
I don't know if there's a better way or if there are limitations to this approach such as cross-origin issues.
Related
I'm working on documenting our existing API's in swagger using open api 3.0.0 specification. I would like to understand the procedure on documenting the contents of a file that is to be uploaded. For e.g.
Say the file that is to be uploaded is response.json, and it has the following content:
{
name: xyz,
age: 50
}
I would like to know the procedure for documenting the above JSON so that clients using our API should provide the file in the aforesaid JSON format.
In Flasgger, I'm trying to create documentation for route which accepts uploaded files. However, despite sticking to the specification, I cannot display file selector in Flasgger UI.
I'm using latest (as of today) flasgger==0.9.1 running OpenAPI 3 specs (as in "openapi": '3.0.0') and I saw this commit in Swagger-UI, that enables file selectors for POST file requests.
I know similar questions were asked before, but none of them related to OAS version 3.
My code snippet is below:
Upload a file
Returns ID of uploaded file
---
tags:
- name: "attachments"
schemes:
- "http"
consumes:
- application/octet-stream
produces:
- application/json
requestBody:
content:
application/octet-stream:
schema:
type: file
format: binary
responses:
200:
... etc
And I get just an empty block input in Flasgger UI. Is it possible Flasgger does not support it even though Swagger-UI does (I thought it's built on top of it)? Or the syntax is wrong?
You are mixing OpenAPI 2.0 and 3.0 syntax. In OAS3, files are described as binary strings, that is type: string and not type: file. Also, the consumes, produces and schemes keywords are not used in OAS3.
Try the following:
Upload a file
Returns ID of uploaded file
---
tags:
- attachments
requestBody:
content:
application/octet-stream:
schema:
type: string # <-------
format: binary
responses:
'200':
description: OK
content:
application/json:
schema:
# ... etc
Note that OAS3 file upload requires Swager UI 3.16.0+ but Flassger 0.9.1 is bundled with UI 3.14.2 and there seems to be no way to update the bundled Swagger UI. This possibility will be added in the next update, Flassger 0.9.2:
https://github.com/rochacbruno/flasgger#externally-loading-swagger-ui-and-jquery-jscss
So you'll need to wait for Flassger 0.9.2.
I also recommend that you check the generated OpenAPI file for syntax errors using the Swagger Editor, because syntax errors might cause incorrect parsing/rendering. This answer explains how to export your OpenAPI file from Swagger UI so that you can use it elsewhere.
I am trying to add a product to the amazon seller account using amazon mws feeds api. I am using Ruby on Rails and peddler gem. But i couldn't find any documentation/example of how to add a new product. There's a function given to submit feed (link). But i am not sure about how to send 'feed_content' parameter. Is there any example of how to do it? I am able to make the connection:
client = MWS::Feeds::Client.new(
marketplace_id: 'marketplace_id',
merchant_id: 'merchant_id',
auth_token: 'auth_token',
aws_access_key_id: 'aws_access_key_id',
aws_secret_access_key: 'aws_secret_access_key'
)
Kindly share any example or any suggestions of how to add a product. Thanks in advance.
FeedContent is the actual content of the feed itself, whether XML or flat file. You also need a FeedType. Have a look at the MWS Feeds API overview to learn about the process. No matter the language or platform you use, the process is the same.
A request is going to look like this:
POST /Feeds/2009-01-01 HTTP/1.1
Content-Type: x-www-form-urlencoded
Host: mws.amazonservices.com
User-Agent: <Your User Agent Header>
?AWSAccessKeyId=0PB842ExampleN4ZTR2
&Action=SubmitFeed
&FeedType=_POST_PRODUCT_DATA_
&MWSAuthToken=amzn.mws.4ea38b7b-f563-7709-4bae-87aeaEXAMPLE
&MarketplaceIdList.Id.1=ATVExampleDER
&SellerId=A1XExample5E6
&ContentMD5Value=ExampleMd5HashOfHttpBodyAsPerRfc2616Example
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2009-01-26T23%3A51%3A31.315Z
&Version=2009-01-01
&Signature=SvSExamplefZpSignaturex2cs%3D
and the body, which contain the products you are adding looks like this:
<?xml version="1.0" encoding="iso-8859-1"?>
<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="amzn-envelope.xsd">
<Header>
<DocumentVersion>1.01</DocumentVersion>
<MerchantIdentifier>M_EXAMPLE_123456</MerchantIdentifier>
</Header>
<MessageType>Product</MessageType>
<PurgeAndReplace>false</PurgeAndReplace>
<Message>
<MessageID>1</MessageID>
<OperationType>Update</OperationType>
<Product>
<SKU>56789</SKU>
<StandardProductID>
<Type>ASIN</Type>
<Value>B0EXAMPLEG</Value>
</StandardProductID>
<ProductTaxCode>A_GEN_NOTAX</ProductTaxCode>
<DescriptionData>
<Title>Example Product Title</Title>
<Brand>Example Product Brand</Brand>
<Description>This is an example product description.</Description>
<BulletPoint>Example Bullet Point 1</BulletPoint>
<BulletPoint>Example Bullet Point 2</BulletPoint>
<MSRP currency="USD">25.19</MSRP>
<Manufacturer>Example Product Manufacturer</Manufacturer>
<ItemType>example-item-type</ItemType>
</DescriptionData>
<ProductData>
<Health>
<ProductType>
<HealthMisc>
<Ingredients>Example Ingredients</Ingredients>
<Directions>Example Directions</Directions>
</HealthMisc>
</ProductType>
</Health>
</ProductData>
</Product>
</Message>
</AmazonEnvelope>
I wrote the following test tweet:
&“”‘’®©™¶•·§–—
Then fetched it using the 'user_timeline' api call. The following json was returned:
...
"text": "&“”‘’®©™¶•·§–—",
...
It seems strange the ampersand is the only escaped symbol.
Are there any other escaped symbols? I can't find a definitive list in the docs.
Alternatively, is it possible to specify if the api should return escaped/ unescaped characters?
Edit
Test tweet:
<>=+
Returns:
...
'text': '<>=+'
...
I just noticed that the respond method in controllers is returning HTML responses in the ISO-8859-1 charset (which garbles my unicode characters). It uses UTF-8 if I set the format to JSON. The render method also uses UTF-8.
I'm using Grails 2.4.4 and the Tomcat plugin v. 7.0.55 in development mode without overriding web.xml. Both grails.converters.encoding and grails.views.gsp.encoding are set to UTF-8. I have <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> in my template if that influences anything.
I've also tried forcing the charset by using respond myInstance, [encoding: "UTF-8"] but it didn't change anything.
Is there something I am not seeing or have I hit a bug?
EDIT: my config.groovy contains the following mime type definitions:
grails.mime.types = [ // the first one is the default format
all: '*/*', // 'all' maps to '*' or the first available format in withFormat
atom: 'application/atom+xml',
css: 'text/css',
csv: 'text/csv',
form: 'application/x-www-form-urlencoded',
html: ['text/html','application/xhtml+xml'],
js: 'text/javascript',
json: ['application/json', 'text/json'],
multipartForm: 'multipart/form-data',
rss: 'application/rss+xml',
text: 'text/plain',
hal: ['application/hal+json','application/hal+xml'],
xml: ['text/xml', 'application/xml']
]
It would seem this is a Grails bug, I've narrowed down the specific case when it happens: you need to have a static responseFormats = ['html', ...] limitation on the controller to trigger it. The fact that Grails' generate-restful-controller includes the responseFormats block automatically makes developers even more likely to encounter this issue.
I've filed a bug report.
EDIT: to keep the responseFormats block but still have UTF-8 responses, it's possible to set the encoding manually, perhaps like this:
def beforeInterceptor = {
response.characterEncoding = 'UTF-8' //workaround for https://jira.grails.org/browse/GRAILS-11830
}