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.
Related
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 ]
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.
When using JSON Schema and Open API specification (OAS) to document a REST API, how do I define the UUID property?
There's no built-in type for UUID, but the OpenAPI Specification suggests using
type: string
format: uuid
From the Data Types section (emphasis mine):
Primitives have an optional modifier property: format. OAS uses several known formats to define in fine detail the data type being used. However, to support documentation needs, the format property is an open string-valued property, and can have any value. Formats such as "email", "uuid", and so on, MAY be used even though undefined by this specification.
For example, Swagger Codegen maps format: uuid to System.Guid in C# or java.util.UUID in Java. Tools that don't support format: uuid will handle it as just type: string.
The only way I found so far is to manually specify the RegEx pattern as reusable schema component:
openapi: 3.0.1
paths:
/transactions/:
post:
responses:
200:
content:
application/json:
schema:
type: object
properties:
transactionId:
$ref: '#/components/schemas/uuid'
components:
schemas:
uuid:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
# the regex above limits the length;
# however, some tools might require explicit settings:
minLength: 36
maxLength: 36
But, I would definitely want to use a more standardized approach.
Since the question was originally asked the JSON Schema spec has been extended to provide built-in support for specifying and validating that a JSON field of type string is a UUID - specifically that it adheres to the format of a UUID as defined by RFC4122, e.g. “f81d4fae-7dec-11d0-a765-00a0c91e6bf6”.
The support was added in JSON Schema spec version 2019-09 (previously known as draft-08). The JSON Schema Validation component spec was extended such that the existing ‘format' keyword that can be specified for schema fields of type string now supports a new built-in format named "uuid".
The example JSON schema below declares a (mandatory) field named "id" of type string that must be formatted as UUID -
{
"$schema": "http://json-schema.org/draft/2019-09/schema#",
"title": "My JSON object schema",
"description": "Schema for the JSON representation of my JSON object.",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for my object. (A UUID specified by RFC4122).",
"type": "string",
"format": "uuid"
}
},
"required": ["id"]
}
Note that at the time of writing, the section of the JSON Schema user guide ("Understanding JSON Schema") covering examples of built-in string validation - JSON Schema Reference > Type-specific keywords > string > Format - doesn’t mention UUID supports, as it’s out of date - it currently only describes JSON Schema draft-7.
For the Java developers among you, the RFC4122 format used by JSON schema is compatible with the string representation of Java’s UUID class - it’s Javadoc also mentions RFC 4122.
For more details see -
The JSON Schema Validator spec section 7. A Vocabulary for Semantic Content With “format” > 7.3. Defined Formats > 7.3.5. Resource Identifiers - The official spec.
This GitHub issue https://github.com/json-schema-org/json-schema-spec/issues/542 (01/2018) requested that support be added. And the enhancement was duly implemented in 03/2019. See pull request https://github.com/json-schema-org/json-schema-spec/pull/715.
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'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