To describe REST APIs in an application-centric matter, I am trying out the ALPS descriptor and its toolings.
Say I have an object "Artwork", an artwork has the following properties: headline, artform, authors, etc.
How should I describe the property "authors"? In OpenAPI spec it is easy, simply say "type: Array", then specify reference under "items". What is the equivalent way of describe a collection in ALPS?
I am using YAML format to describe the API.
My current descriptors looks like this:
descriptors:
# vocabulary properties
- id: "identifier"
type: "semantic"
text: "Unique identifier within Alpha Org. This is not the serial number of the item. This identifier is automatically generated when a new artwork item is created in the system."
ref: "https://schema.org/identifier"
- id: "headline"
type: "semantic"
text: "Title of the artwork"
ref: "https://schema.org/headline"
- id: "artform"
type: "semantic"
text: "Form of the artwork: painting? photograph? sculpture? others?"
ref: "https://schema.org/artform"
- id: "authors"
type: "semantic"
text: "Authors of this artwork"
ref: "https://schema.org/author"
- id: "serialNumber"
type: "semantic"
text: "Serial number of the artwork. If the artwork does not have a serial number, such as an original painting from an artist, then this number is simply the examplar number, usually 1."
ref: "https://schema.org/serialNumber"
- id: "description"
type: "semantic"
text: "Description of the artwork"
ref: "https://schema.org/description"
- id: "obtainDate"
type: "semantic"
text: "Date on which Alpha Org obtained the ownership of this artwork."
ref: "https://schema.org/Date"
- id: "itemLocation"
type: "semantic"
text: "Location of the storage of the artwork item"
ref: "https://schema.org/itemLocation"
- id: "images"
type: "semantic"
text: "Images of the artwork"
ref: "https://schema.org/image"
ALPS descriptions don't make distinctions between single items and collections. From the model POV anything could be a collection, from the implementation POV, each service implementing that ALPS description makes their own decisions.
as a common practice, i typically use the IANA link-rel values when it is important
rel: item and rel: collection
there's a small utility (ALPS UNIFIED) that shows how to convert ALPS descriptions into OpenAPI definitions:
https://github.com/mamund/alps-unified
Related
/{ca}/{en}/{v1}:
uriParameters:
ca:
description: Country of users have to specify with two letter country code.
type: string
required: true
minLength: 2
maxLength: 2
en:
description: Language have to specified either English or French.
enum: [en,fr]
type: string
required: true
v1:
description: The version of the API need to be either v1 or v2.
enum: [v1,v2]
type: string
required: true
I am trying to create a schema which includes key - value arrays, but the properties are themselves separately defined. For example, lets say I would like to describe a file with following properties:
id
fileName
fileType
where fileType is an object with id and a specific set of acceptable key-value combination, for example
0, Word
1, Excel
2, PDF
... etc
I am a bit confused on how to describe this with OpenApi 3 as from the documentation I can't seem to find a way to describe arrays with specific key - value combinations.
Right now I am using an enum like below
components:
schemas:
fileType:
type: string
description: file type
enum:
- Word
- Excel
- PDF
but that is inadequate.
Thanks
You can use something like this:
Your fileType Schema
components:
schemas:
fileType:
type: object
description: file type
properties:
1:
type: string
example: "Word"
2:
type: string
example: "Excel"
3:
type: string
example: "PDF"
Here is your requestBudy
requestBody:
description: File
content:
'*/*':
schema:
properties:
id:
type: string
fileName:
type: string
fileType:
$ref: '#/components/schemas/fileType'
Looks like
Hope this help.
I resolve most of my problem only few left out of which this one is preventing me to submit the form. I am using Nativescript + vue and without Typescript. how to display the Valueproviders with array list? Here is the code
https://play.nativescript.org/?template=play-vue&id=2oWObE
There was the problem with your data type. As per the documentation Array should have key and label properties. But still if you want id and name then you should try like below.
'valuesProvider': {
key: 'id',
label: 'name',
items: [
{ id: 1121, name: 'Shanghai' },
{ id: 3651, name: 'Lagos' },
{ id: 5213, name: 'Moscow' },
{ id: 6214, name: 'São Paulo' },
{ id: 6985, name: 'Sydney' }
]
};
https://docs.nativescript.org/vuejs/ns-ui/DataForm/dataform-editors-providers
Anyway, I tried that and that was not working for me either then searched for it and relaised that there is an open feature request to support the valuesProvider for picker from JSON metadata. You can vote to support the same feature.
https://github.com/NativeScript/nativescript-ui-feedback/issues/369
Solution
Just get you cityList out of vue data and map your data
https://play.nativescript.org/?template=play-vue&id=2oWObE&v=6
more detailed version with groups
https://play.nativescript.org/?template=play-vue&id=rqK7wO&v=3
I am having trouble figuring out a way to create a DELETE method for the POST method I just created in my API design. The post takes in a requestBody of the GlobalOrderSetupInfo, within that object there is another object that will be an array of different sessions that I want to add the GlobalOrderSetupInfo info to, in the delete method I need that same info deleted but you cannot have a delete method with a requestBody. How do I go about creating it?
Here is my post method:
'/api/globalorderdays':
post:
tags:
- Setup Global Order Days
summary: Allows user to add orderdays to multiple sessions
requestBody:
required: true
description: put text here
content:
application/json:
schema:
type: object
items:
$ref: '#/components/schemas/GlobalOrderSetupInfo'
responses:
'201':
description: Created
'400':
description: Bad request
'401':
description: Unauthorized
components:
schemas:
GlobalOrderSetupInfo:
description: 'Put Text Here'
type: object
properties:
Id:
type: integer
AvailableHolidayList:
type: string
SelectedOrderHolidays:
type: string
example: "New Year's Day, President's Day, Memorial Day, Labor Day, Veterans Day, Thanksgiving Day, Chistmas Day"
SelectedHolidays:
type: string
example: "New Year's Day, President's Day, Memorial Day, Labor Day, Veterans Day, Thanksgiving Day, Chistmas Day"
OrderDays:
type: string
example: "01/01/2000"
NoOrderDays:
type: string
example: "01/01/2000"
AllSessionList:
uniqueItems: false
type: array
items:
$ref: '#/components/schemas/SessionInfoList'
SessionIdString:
type: string
example: "15"
SessionInfoList:
description: 'Put Text Here'
type: object
properties:
Id:
type: integer
SessionID:
type: integer
Name:
type: string
example: "Harbor"
Type:
type: string
GroupName:
type: string
example: "PHACTS"
IsChecked:
type: boolean
default: false
example: true/false
SetupID:
type: string
Typically your POST method creates a new entity, and returns the id of that entity. Then you might have additional routes to GET that entity by ID, update (PATCH) it, or DELETE it.
So in your example, the entry for DELETE might look like:
'/api/globalorderdays/{id}':
parameters:
- in: path
name: id
required: true
schema:
type: integer
get:
summary: Get orderdays by id
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalOrderSetupInfo'
delete:
summary: Delete orderdays by id
responses:
'204':
description: Deleted
'404':
description: id not found
'401':
description: Unauthorized
I am trying to write the Swagger spec for a service that posts an array of objects as request body. I would like the user to be able to test the service with a specific set of multiple different complex objects in the array as the default sample inputs.
So far I have the following code defining the service and complex object:
paths:
/myService
post:
summary: test 123
description: test 123
parameters:
- name: bodyParamsObject
description: 'Object containing any / all params in the body'
in: body
required: true
schema:
properties:
data:
$ref: '#/definitions/myInputArray'
responses:
200:
description: OK
schema: myOutputArray
definitions:
myInputArray:
type: array
items:
$ref: '#/definitions/myComplexObject'
myOutputArray:
type: array
items:
$ref: '#/definitions/myComplexObject'
myComplexObject:
type: object
properties:
description:
type: string
example: 'Example Item'
size:
example: 552
type: integer
format: int32
hasAdditionalProperties:
type: boolean
example: true
The output array is coming back correctly, but there is only one item in the model schema.
How can I make the sample request body contain multiple different items in the array?
I was able to solve this by using the example property on the object definition and filling it with the array in json.
definitions:
myInputArray:
type: array
items:
$ref: '#/definitions/myComplexObject'
example: [
{
"description": "Example Item 1",
"hasAdditionalProperties": true,
"size": 750,
},
{
"description": "Another example",
"hasAdditionalProperties": false,
"size": -22,
},
{
"description": "Last one",
"hasAdditionalProperties": true,
"size": 0,
}
]
myComplexObject:
type: object
properties:
description:
type: string
example: 'Example Item'
size:
example: 552
type: integer
format: int32
hasAdditionalProperties:
type: boolean
example: true