GimpMaster
commented
5 years ago Bumping up this issue. We pretty much use the request body as our POST method for passing parameters. We use: "application/json" as the content type. We then define the parameters giving some as required and non-required as well as examples. This renders perfectly in ReDoc but Apicurio provides no way to edit this other than in the source code. Here is a working endpoint example that renders great in ReDoc, it even imports in Apicurio but there is no method to edit it in a GUI fashion.
post:
tags:
- Order
summary: Order Failed
description: >
Call this endpoint on order failure. The fields below are for your convenience for updating any
particular value that has changed. The important parameter is the status value.
operationId: order_failed
requestBody:
content:
application/json:
schema:
required:
- status
- source_order_id
properties:
id:
description: (Optional) If provided it will update a previous order's information.
type: integer
example: 12345
first_name:
description: The customer's first name.
type: string
example: John
last_name:
description: The customer's last name.
type: string
example: Doe
email:
description: The customer's email.
type: string
example: john@doe.com
phone:
description: The customer's phone number.
type: string
example: +1-555-555-4444
currency:
description: (Optional) Provide a different currency then the merchant's default currency.
type: string
example: CDN
source_order_id:
description: A vendor specific order source id.
type: string
example: '#123-MERCH'
subtotal:
format: double
description: The order subtotal.
type: number
example: 12.34
subtotal_usd:
format: double
description: The order subtotal as fractional US dollars.
type: number
example: 12.34
taxes:
format: double
description: The taxes applied to the subtotal.
type: number
example: 0.62
taxes_usd:
format: double
description: The taxes applied to the subtotal in US dollars.
type: number
example: 0.62
insured:
description: A flag indicating whether an order is insured. 0 = not insured.
type: integer
example: 1
paid_to_insure:
format: double
description: Amount of money paid to insure package
type: number
example: 0.98
paid_to_insure_usd:
format: double
description: Amount of money paid to insure package in US dollars
type: number
example: 0.98
amount_covered:
format: double
description: Amount of subtotal that is covered by insurance.
type: number
example: 12.34
amount_covered_usd:
format: double
description: Amount of subtotal that is covered by insurance in US dollars.
type: number
example: 12.34
status:
description: The current status of the order.
enum:
- completed
- canceled
- failed
- created
type: string
example: failed
line_items:
description: Line item details stored as a JSON string.
type: string
example: '{}'
exchange_rate:
format: double
description: Exchange rate that overrides the merchant's default rate.
type: number
example: 0.034
destination:
description: The shipping destination for the order.
type: string
example: 123 Elm St. Seattle WA
created_on:
description: The created on date as milliseconds since Unix Epoch
type: integer
example: 10456868456
updated_on:
description: The updated on date as milliseconds since Unix Epoch
type: integer
example: 10456868456
customer:
description: >
(Optional) Provide a JSON object to create a Customer specific for this order.
If left blank the order email will be used to look up a customer or a new
customer will be created.
type: object
properties:
first_name:
description: Customer's first name.
type: string
example: John
last_name:
description: Customer's last name.
type: string
example: John
email:
description: Customer's email address.
type: string
example: john@doe.com
phone:
description: Customer's phone number.
type: string
example: +1-555-555-3333
street_address1:
description: Customer's street address
type: string
example: 123 Elm St.
street_address2:
description: Customer's street address
type: string
example: 'Suite #110'
city:
description: Customer's city
type: string
example: Seattle
province:
description: Customer's province
type: string
example: Washington
zip:
description: Customer's zip code
type: string
example: '55555'
country_code:
description: Customer's 2-digit country code
type: string
example: US
required: true
responses:
'200':
description: Returns a success object.
content:
application/json:
schema:
type: object
properties:
result:
description: Result of the operation. Should always be success.
type: string
example: success
id:
description: The unique identifier of the order.
type: integer
example: 123454
security:
-
Merchant Access Token: []
EricWittmann
anatoli26
Ranbato
osamaramihafez
I'm not sure this is something that the OpenAPI mandates to be implemented the way it is now, but currently there is no way to define a set of properties for a Request body, it's only possible to select a single data type - either a basic one (int, string) or one of the data types defined by the user.
Also, one can't define multiple request bodies with the same media type (e.g. application/json).
I have an example at hand right now: a
userdata type that hasfirstname,lastname,email,enabled,adminand other properties as part of the data type, but notpassword. ThePATCHmethod could be used to change any of the properties if the user is admin, and onlyfirstname,lastnameandemailif the user is a regular user. This method could also be used to change thepassword, but in this case either aprt(password reset token) should be provided or the currentpasswordand a newpassword(password_new) if the user is changing his own password. Or, if the user is admin and changing other user's password, justpassword_newis enough.Today I have to either create multiple
userdata types for all this combinations or to embed all the possible fields with the explanation of each combination and condition to a singleuserdata type, or (as I do it now) to specify everything in the description of the method and provide the possible combinations in the examples of the single request body media type 'application/json'.I believe it would be better to be able to define multiple request body variants with the same media type and custom properties sets, maybe with a Name and a Description for each one (basically, for the request bodies to be definable the same way the user data types are).