I am starting in programming and I need to update an asyncapi.yaml file including an enum of different statuses, and I am also being asked to add descriptions to each of them.
While updating this new features to the openapi.yaml used the following schema:
I can´t find related documentation to confirm that I am complying with the AsyncAPI specs. I got to some discusions regarding this situation but I just can´t get it clear.
Could you please help me defining if this schema complies with AsyncAPI spec? Any reference to documentation to clarify? Does OpenAPI and AsyncAPI adhere to same schemas or go in their own pace?
Please understand my level of english. Thank you!
SFCCOrderNotification:
type: object
properties:
id:
type: string
description: The order's ID.
created_at:
type: string
format: date-time
description: The order's creation date.
modified_at:
type: string
format: date-time
description: The order's last modification date.
status:
$id: Status
type: string
description: |
The order's status.
* `submitted` - the customer has placed an order through e-commerce.
* `received` - the order has been generated successfully. It has not yet been processed by the ERP.
* `processing` - the order is somewhere between the integration in the ERP and the logistics operator's system. If it is taking a long time, there may have been a technical error in the communication. Requires manual action.
* `pending_merchandise` - the order has been successfully integrated in the logistics operator but one or more items of the order are out of stock.
* `picking` - the workers of the logistics operator are picking the order.
* `cancelled` - the order has been cancelled manually.
enum:
- submitted
- received
- processing
- pending_merchandise
- picking
- cancelled
billing_address:
$ref: '#/components/schemas/Address'
order_items:
type: array
items:
$ref: '#/components/schemas/OrderItem'
required: [ id, status, modified_at, billing_address, order_items, shipments, payment_info, price_info ]
Related
I have this api documentation written in OpenAPI 3.0.3
openapi: 3.0.3
info:
version: '1.0'
title: 'MyTitle'
description: Specification for Bear Store
servers:
- url: https://development.example.com/v1
description: Development Server
paths:
'/v1/bears':
get:
description: Requests a lists all the bears
summary: List of bears request
responses:
'200':
description: List of Bears
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
I have a Bear object that has id, and name properties. I want to define that id field is a unique field. How can I define this in OpenAPI 3?
OpenAPI lets you define a field's type and its expected format. But it's not possible for it to ensure its uniqueness.
Uniqueness is a business concern, which might involve non-trivial checks. Therefore, it's outside the scope of OpenAPI/Swagger to formalize such concepts.
However, you can add a description to explain the requirement that the field value must be unique, then implement necessary checks in the API to ensure that the value supplied by the client is actually unique.
This question already has answers here:
Re-using model with different required properties
(2 answers)
Closed 3 years ago.
This is my code:
definitions:
User:
type: object
properties:
id:
type: integer
username:
type: string
first_name:
type: string
last_name:
type: string
password:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- username
- first_name
- last_name
- password
/api/users:
post:
description: Add a new user
operationId: store
parameters:
- name: user
description: User object
in: body
required: true
type: string
schema:
$ref: '#/definitions/User'
produces:
- application/json
responses:
"200":
description: Success
properties:
success:
type: boolean
data:
$ref: '#/definitions/User'
As you can see, in the post key under /api/users I used the User definition as my schema on it.
I want to lessen my code so I reused the User definition as my schema. The problem here is that I do not need the id, created_at and updated_at fields.
Is there a way to just inherit some of the fields except the fields mentioned? Also, I would love some suggestions to make it better since I'm trying to learn swagger. Thank you.
As explained in this answer to a similar question:
You would have to define the models separately.
However, you have options for the cases of exclusion and difference.
If you're looking to exclude, which is the easy case, create a model
of with the excluded property, say ModelA. Then define ModelB as
ModelA plus the additional property:
ModelB:
allOf:
- $ref: "#/definitions/ModelA"
- type: object
properties:
id:
type: string
If you're looking to define the difference, follow the same method
above, and exclude the id from ModelA. Then define ModelB and ModelC
as extending ModelA and add the id property to them, each with its own
restrictions. Mind you, JSON Schema can allow you to follow the
original example above for some cases to "override" a definition.
However, since it is not really overriding, and one needs to
understand the concepts of JSON Schema better to not make simple
mistakes, I'd recommend going this path for now.
Is there a way to exclude one or more properties from a request body when you use a type and writing your API using RAML 1.0
I'll explain. I have a type: 'Order' with a set of properties. I have a resource /orders and a method post which allows users to create a new order.
The request body is an order struct json and a response is an order struct as well.
But I don't want users to specify order id while they are submitting their request. But that id (and a couple more 'response only' fields) will be returned at the response. I don't want to create an extra type, like OrderRequest and then inherit it with an Order type, maybe there is a more elegant solution?
So I want to have a way to exclude some properties from a request body and keep others in order to use their description and examples.
Thanks and sorry for my English :)
Use two types. The second will be child of the first. Example:
#%RAML 1.0
title: GitHub API
version: v3
baseUri: https://api.github.com
mediaType: application/json
types:
OrderCreating:
type: object
properties:
products:
description: List of product ids with amount.
required: true
type: object
properties:
[]:
type: number
coupon?: string
Order:
type: OrderCreating
properties:
id: integer
price: number
...
/orders:
post:
body:
application/json:
type: OrderCreating
/{orderId}:
get:
responses:
200:
body:
application/json:
type: Order
Also you can include Library with declaration of your types.
As you don't want to create an extra type with inheritance you can still mark the field as optional and document that it is present in the response.
I am writing my first Swagger spec for a search endpoint and wondering if there is a simple way to negate a search parameter.
Here is the yml for searching by brand:
properties:
brand:
description: The magazine that produced the original article
type: string
I would also like our users to be able to search by excluding a brand (eg either "from [brand]" or "not from [brand]". Is there a more graceful approach than creating duplicate properties for each parameter (eg, both brand and notBrand)?
I'd suggest the following. If you are using query parameters for the search endpoint (which is probably smart), you should consider having a querystring parameter like such:
- name: brand
in: query
type: array
items:
type: string
You can have another query parameter for excludes which follows the same syntax. Be sure to set the collectionFormat depending on how your API will parse the query string, since arrays are simply not standardized across frameworks. Read here for more details.
I'm declaring a REST service API stub in RAML. My web application provides equipment, which can be listed, obtained by id or by code. When I want the whole list, I don't specify any URI parameter, however, to get a concrete equipment, I do. That's its current state:
/equipment:
get:
body:
application/json:
application/xml:
description:
List all the equipment
/id/{equipmentId}:
get:
body:
application/json:
application/xml:
description:
Get an equipment by id
/code/{code}:
get:
body:
application/json:
application/xml:
description:
Get an equipment by code
Here, in description fields I write what the current call performs. However, I would like to add a description for the parameter passed in the URI itself (id or code). Is there a way to achieve it?
You are missing uriParameters sections to describe the equipmentId and code parameters. In such section, you can specify the usual: type, description...
See section Template URIs and URI Parameters in the spec: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md#template-uris-and-uri-parameters