While using swagger-editor I create the below YAML that shows an example of the response object. It's properly displaying in the swagger-editor. When I then download the JSON and display it in swagger-ui, the example is completely missing.
/person/{email}/create:
post:
summary: Create a new account
tags:
- Person
parameters:
...
responses:
201:
description: The new SQL ident and sport details
examples:
application/json: |
[
12,
[
{
"sql_idnet" : 12,
"name" : "Basketball"
},
{
"sql_ident" : 13,
"name" : "Ice Hockey"
}
]
]
This might be because the response does not have a schema - in Swagger this means the response does not have a body.
That said, Swagger UI 3.0 displays this example correctly.
Swagger UI and Swagger Editor currently do not support multiple examples. You can follow this issue for updates.
Related
I was trying to add a file upload option for a POST request in Swagger UI by following the documentation.
The problem is this:
As you can see, Swagger UI does not render anything, neither for textual inputs nor for file inputs.
I tried to search on SO other answers about this but nothing.
This is the request body that I defined for the requestBody parameter of the path:
CreateTicketMessagePayload:
description: |-
Request multipart body required to proceed in the ticket message creation processes.
**Object part**:
```
{
"message": "Textual content of the message",
"private": "Flag that indicates the message is visible just for technicians"
}
```
**File part**:
"attachment": Message attachment file.
content:
multipart/form-data:
schema:
type: object
properties:
message:
type: string
example: This is a message
private:
type: boolean
example: false
attachment:
type: string
format: binary
What am I doing wrong?
In case of multipart/form-data requests, Swagger UI shows the inputs after you click "Try it out".
There's an existing enhancement request to display the inputs by default:
Display static documentation information for multipart properties in OpenAPI 3.0 files
I am trying to create a JSON that will be parsed with OpenApi 2.0 swagger definition in Microsoft Power Automate Custom connector.
This is the JSON i have currently
"connectionParameters" : {
"param1" : "value1",
"param2" : "value2"
}
I want to provide an alternative connection parameter schema, in which user has the option to choose from a set of params to provide value. This can be achieved in OpenAPI 3.0 in the following way:
"connectionParameters" : {
anyOf : [
{
"param1" : "value1",
"param2" : "value2"
},
{
"alternateparam1" : "value1",
"alternateparam2" : "value2"
}
]
}
How can this be achieved in OpenAPI 2.0? "anyOf" is not available in OpenAPI 2.0 definition. I have explored the "discriminator" construct but couldn't find any implementation that I can provide with my JSON schema.
Personally, I think the approach you're trying with v3.0 would be a little confusing for the end user as I don't really understand what they'd actually be selecting in a dropdown persay.
I think your best bet (given you're limited anyway) is to use the ENUM keyword to define a basic list of values that when selected and passed into your API, you do the work in the background to select the more advanced objects that you've listed in your question.
https://swagger.io/docs/specification/data-models/enums/
I am creating a well-organized OAS3 swagger documentation on swaggerhub. For every endpoint i am writing all possible answers like 200, 201, 204, 400, 401, 403, 404, 500 etc. In addition all methods have default parameters like X-Language-Code etc.
I am in such a place that the responses, models, parameters I use now begin to repeat themselves in each file. After a little research i learnt that i can create a domain and remote absolute url references to them.
There is no error when i used the 'definition's remotely like this:
/example:
get:
#some other informations here
responses:
200:
description: 'example description'
content:
application/json:
schema:
$ref: 'https://remote.example/url/2.0#/definitions/ExampleResponse'
But, apparently you can not use $ref keyword right below responses or 400 etc.. keyword like this:
This one not getting error but not rendering the remote reference
responses:
400:
$ref: 'https://remote.example/url/2.0#/responses/Error400'
or this:
This one gives error
responses:
$ref: 'https://remote.example/url/2.0#/responses'
Even, i can not use 'parameters' as i expected:
/example:
get:
parameters:
- languageCode:
$ref: 'https://remote.example/url/2.0#/parameters/languageCode'
/example:
get:
parameters:
- $ref: 'https://remote.example/url/2.0#/parameters/'
I dont want to rewrite all reference definitions below every documentation.
I am confused about using and referencing 'domain's. Can someone explain or referencing a document about this situations since i couldn't found any documentation about it.
Update: OpenAPI 3.0 domains are now supported in SwaggerHub.
As of December 2018, SwaggerHub domains only support the OpenAPI 2.0 syntax but not OpenAPI 3.0. OpenAPI 3.0 and 2.0 use slightly different syntax for parameters, responses, etc., this means you cannot reference an OAS2 domain from an OAS3 API definition.
The workaround is to create another OpenAPI 3.0 API in SwaggerHub and use it as a "domain". You'll need to add a dummy header with openapi: 3.0.0, the info section and empty paths: {} to make the validator happy.
openapi: 3.0.0
info:
title: Common components
version: 1.0.0
paths: {}
# Put your common components here:
components:
schemas:
...
parameters:
...
responses:
...
Then you can reference components from this "domain" using the usual $ref syntax:
$ref: 'https://api.swaggerhub.com/apis/USERNAME/API-NAME/VERSION#/components/responses/Error400'
Make sure the hostname in $refs is API.swaggerhub.com (not APP.swaggerhub.com) and the link contains /apis/ (not /domains/).
Currently my swagger output as a body parameter that looks like this
{
"name": "body",
"in": "body",
"description": "",
"required": true,
"type": "file"
}
and i read the documentation that the type property can be a array of types
{
"name": "body",
"in": "body",
"description": "",
"required": true,
"type": [null,"file"]
}
but I have found no way to tell aspnet core mvc or swaggerGen to output two types? Is this possible.
I would like the swaggerUI to include the option to either select a file or post some json data. Can this be done?
and i read the documentation that the type property can be a array of types
"type": [null,"file"]
This is not valid in OpenAPI/Swagger. type must be a single type, and there's no null type.
I would like the swaggerUI to include the option to either select a file or post some json data.
In OpenAPI/Swagger 2.0 this is not possible – an operation can post either a file or JSON but not both. You'll need two operations - one that accepts JSON, and another one that accepts a file.
What you want will be possible using OpenAPI 3.0. However, I don't know if ASP.NET Core MVC supports OpenAPI 3.0; it may take some time before tools adopt the new version of OpenAPI.
Your API spec (in YAML) would look like this:
paths:
/something:
post:
requestBody:
description: Either a file or JSON object
required: true
content:
application/json:
schema:
type: object:
properties:
...
# Post a file via a multipart request
multipart/form-data:
schema:
type: object
properties:
file: # <-- here "file" is a form field name
type: string
format: binary
required:
- file
# or maybe...
# Post a file directly
application/octet-stream:
schema:
type: string
format: binary
responses:
...
A Post entity (https://msdn.microsoft.com/en-us/library/mt607553.aspx) cannot be created using Dynamics CRM 2016 Online Web API.
This payload should create a post on POST /api/data/v8.1/posts
{
"text": "Test Single Post",
"source": 1,
"type": 7
}
(source 1 is an auto post, type 7 is a status post)
But it returns:
{
"error":
{
"code":"",
"message":"An unexpected error occurred.",
"innererror"
{
"message":"An unexpected error occurred..."
}
}
}
Submitting the same payload with only "text" fails too.
Notice that the Post entity does not have single-valued navigation properties (https://msdn.microsoft.com/en-us/library/mt607553.aspx#bkmk_SingleValuedNavigationProperties) that will allow me to set the related entity (contact, account, etc).
For example, Creating a Task entity (https://msdn.microsoft.com/en-us/library/mt607619.aspx) works fine on POST /api/data/v8.1/tasks
{
"subject": "Test Single Task",
"description": "Test One Description of Task",
"regardingobjectid_contact_task#odata.bind": "/contacts(<someguid>)",
"scheduledend": "2016-07-21T12:11:19.4875892Z"
}
It seems to me that Post should expose something like regardingobjectid_contact_post#odata.bind, but it does not.
For context, this is how to create a Post via the SOAP endpoint and the SDK:
var result = Client.getOrganizationService().Create(new Post
{
Text = post.text,
RegardingObjectId = new EntityReference(
entityName,
Guid.Parse(post.regarding_guid)
)
});
Does anyone have a working example of a Post created via the Web API? Is this an omission in the Dynamics CRM Web API?
It doesn't look like this is listed in the limitations: https://msdn.microsoft.com/en-us/library/mt628816.aspx
UPDATE
It appears that the postregarding entity is where the link should be created to contact/account. This can be demonstrated by querying:
/posts?$filter=postregardingid/regardingobjectid_contact/contactid eq <someguid>
However, a "deep insert" like so does not work:
{
"text":"sometext",
"postregardingid":
{
"regardingobjectid_contact#odata.bind":"/contacts(someguid)"
}
}
The response is
Cannot create child entities before parent entity.
Nowhere it's mentioned like Post (activity feed) cannot be created using webapi. In fact it's not listed as crm webapi limitation like you pointed out.
Also on comparison, _regardingobjectid_value lookup property of post is different from activitypointer. Single valued navigation property too.
Out of curiosity, My investigation moved towards the Partner - post_PostRegardings
Only thing making sense - postregarding is strictly internal use. This could be the reason for all such behavior. This is my theory per v8.2 today(Aug 12 2017)
Description: Represents which object an activity feed post is regarding. For internal use only.
Entity Set path:[organization URI]/api/data/v8.2/postregardings
Base Type: crmbaseentity EntityType
Display Name: Post Regarding
Primary Key: postregardingid
Ref: https://msdn.microsoft.com/en-us/library/mt608103.aspx
Update:
Looks like MS recommend the community to use Organization service to create a custom Post record. Web api is still broken. Read more
I was recently struggling with this issue with an Activity table made using powerapps. For those who are interested, here's my post request:
POST: https://<MY_DOMAIN>.crm.dynamics.com/api/data/v9.1/<TABLE_NAME>
{
"regardingobjectid_contact#odata.bind": "/contacts(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)",
"description": "data for this entity",
"subject": "more data"
}
I didn't do anything different from other peoples' answers. I'll give an update if this problem fails sporadically. But as it is right now, it looks like regardingobjectid may be working in version 9.1
using D365 Api v9.1
POST https://{domain}.crm4.dynamics.com/api/data/v9.1/posts
{
"regardingobjectid_contact#odata.bind":"/contacts(guid)",
"text": "This is a private message post",
"source": 1,
"type": 4
}
source :
Auto Post
Manual Post
ActionHub Post
type :
Check-in
Idea
News
Private Message
Question
Re-Post
Status