In OpenAPI 3.0, I'm wondering what the difference is when describing parameters. For example, what is the difference between descriptions "Foo" and "Bar" below? Is the one for "Foo" more for the semantics of the parameter and the one for "Bar" more for the syntax, if that makes sense? Should just one be used generally (and which if so)?
{
"name": "someParameter",
"in": "query",
"description": "Foo",
"schema": {
"type": "string",
"description": "Bar"
}
}
The parameter description is specified by the description in the parameter itself.
It just so happens that parameters use a schema to define the data type, and schemas can have their own description. In the context of parameters, you can think of the schema-level description as the description of the parameter's data type.
The two descriptions are semantically separate. Schema-level decription is NOT a fallback for missing parameter description.
Here's another example:
paths:
/users/{id}:
delete:
summary: Delete a user
parameters:
- in: path
name: id
required: true
description: The ID of the user you want to delete.
schema:
type: string
format: uuid
description: >-
A unique identifier in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx".
In practice, parameters usually don't have a schema-level description specified because it's often redundant.
Related
I'm trying to model my API using swagger and the Open API 3.0 specification. I have made some schemas and now I'm modeling the response of my endpoints. The problem is that they return something like this:
[
{
"name": "this attribute is always here"
"type1": { "description": "this maybe appear or not" },
"type2": { "description": "this maybe appear or not" },
...
"typeN": { "description": "N is not a fixed number, it may range from 0 to another positive integer" },
}
]
I know how to model the array and the object (with the name property). The problem comes when I have to model the typeX properties, I do not know how to specify that they are optional and the number of ocurrences is variable. Any idea?
This object is basically a string-to-object dictionary/hashmap with an extra name property. Fixed properties are defined in properties, and the dictionary part can be defined using either patternProperties (in OpenAPI 3.1) or additionalProperties (in OpenAPI 3.0 and 2.0).
OpenAPI 3.1
In OAS 3.1 your object can be defined as follows. Since the optional property names all follow the typeX format, the schema uses patternProperties to define the regex for the property names.
MyObject:
type: object
required: [name]
properties:
name:
type: string
patternProperties: # <-- This part defines the "typeX" properties
^type\d+$: # <-- Property name regex
type: object # <-- Property value
properties:
description:
type: string
additionalProperties: false # No other properties other than "name" and "typeX"
OpenAPI 3.0 and 2.0
In earlier OAS versions, you use additionalProperties to define "may have extra properties with <such> values", but there's no way to define the format of those property names. You can however mention the property name format in the schema description and also add a schema example for documentation purposes.
MyObject:
type: object
description: >-
In addition to the `name` property, this object may have an arbitrary
number of properties named `typeX` where X is a positive integer.
required: [name]
properties:
name:
type: string
additionalProperties:
# This part defines the *value* of the typeX properties
type: object
properties:
description:
type: string
# Optional schema example
name: something
type1:
description: ....
type2:
description: ....
I'm implementing an OpenAPI-3.0 spec for my API, and I plan on using sparse fieldsets as a parameter for GETs. The examples for parameters using style=deepObject are a little sparse, so I'm not sure if I've got this exactly right.
- in: query
name: fields
style: deepObject
schema:
type: object
additionalProperties:
type: string
Can I combine both the deepObject and additionalProperties options?
I want to support flexible query parameter inputs like this:
GET /articles?include=author&fields[articles]=title,body&fields[people]=name
but I don't want to have to spell out every single option for each resource and field.
Your definition is correct. You might also need to add allowReserved: true so that the comma in =title,body is not percent-encoded, and you can add a parameter example value for documentation purposes:
- in: query
name: fields
style: deepObject
allowReserved: true
schema:
type: object
additionalProperties:
type: string
example:
articles: title,body
people: name
When using "try it out" in Swagger UI, enter the parameter value in the JSON format like so:
{
"articles": "title,body",
"people": "name"
}
Swagger UI will serialize the parameter as
?fields[articles]=title,body&fields[people]=name
I am trying to use rest to create fields and picklists, on the web site I created a field as type picklist String and added some items to the list:
Rest url for field:
https://dev.azure.com/{org}/_apis/work/processes/{processId}/workitemtypes/CMMI2.Bug/fields/Custom.AppType?api-version=5.0-preview.2
it is returning this:
{
referenceName: "Custom.AppType",
name: "AppType",
type: "string",
description: "",
url: "https://dev.azure.com/{org}/_apis/work/processes/bd96307e-3d16-44ac-b498-be1a8daff2d5/behaviors",
customization: "custom"
}
Rest URL for picklist:
https://dev.azure.com/{org}/_apis/work/processes/lists/{picklistId}?api-version=5.0-preview.1
this returns:
{
items: [
"All",
"Item2",
"Item3"
],
id: "{picklistId}",
name: "picklist_{diffGuidFromPickListId}",
type: "String",
isSuggested: false,
url: "https://dev.azure.com/{org}/_apis/work/processes/lists/{picklistId}"
}
Here is documentation for this:
https://learn.microsoft.com/zh-cn/rest/api/azure/devops/processes/fields/get?view=azure-devops-rest-5.0#processworkitemtypefield
Firstly - why is type of field string when it should be picklistString (as per documentation link)?
Secondly - how is the picklist linked to the field?
thanks
The picklistString refers to the name of the type, its actual property is string, so the field type it displays in type is string.
Secondly - how is the picklist linked to the field?
(1) To achieve this, you can use this API:
POST https://dev.azure.com/{organizationName}/{projectName}/_apis/wit/fields?api-version=5.1-preview.2
Here is my request body for you reference:
{
"name": "{FieldName}",
"referenceName": "{the reference name of WIT},
"type": "string",
"usage": "workItem",
"readOnly": false,
"canSortBy": true,
"isQueryable": true,
"supportedOperations": [
{
"referenceName": "{the reference name of WIT}"
"name": "="
}
],
"isIdentity": true,
"isPicklist": true,
"isPicklistSuggested": false,
"url": null
}
Note: Set isPicklist as true, and you can link picklist to this new field.
(2) For UI operation, just add new field, open the drop-down list of type and select picklist(string)/picklist(Integer) as what you need.
The difference between picklist(string) and picklist(Integer) is that picklist(string) allow a pick list of short text string (255 characters or less) values, and picklist(Integer) contains a pick list of Integer values.
It would appear that this is all moot, since the picklistId property cannot be changed once it has been set (i.e. at field creation).
In this reference material, picklistId has "No" as its value for the "Can change?" column: https://learn.microsoft.com/en-us/azure/devops/boards/work-items/work-item-fields?view=azure-devops
I generate the metadata from the database following the http://www.breezejs.com/documentation/load-metadata-script
My question is : How can I generate the metadata for two entities that has the same name but a different shema in the database ?
I tried to use a qualified name for my entities like this : ...
"entityType": [
{
"name": "Admin.RefactorColumn",
"key": {
"propertyRef": {
"name": "Id"
}
},
"property": [
{
"name": "Id",
"type": "Edm.Int32",
"nullable": "false",
"annotation:StoreGeneratedPattern": "Identity"
}, ...
...
the problem is that when I make entityManager.saveChanges() and return the saveResult(also made by hand) from server breeze look for an entity with the name RefactorColumn:#Admin ... instead of Admin.RefactorColumn:#...
I have no issue if name is just "RefactorColumn" instead of "Admin.RefactorColumn"
Can I solve this issue changing the metadata format or the saveResult format ?
Thank for any help !
All breeze EntityTypes have a concept of a namespace qualified name. This name is a composition of a 'shortName' and a 'namespace'. As of breeze 1.4.16 a qualified name can be created by calling the EntityType.qualifyTypeName static function. i.e.
var shortName = "Employee";
var namespace = "My.Qualified.Namespace";
var qualifiedName = breeze.EntityType.qualifyTypeName(shortName, namespace);
// qualifiedTypeName will be => "Employee:#My.Qualified.Namespace"
In general, all breeze APIs will accept either a shortName OR a qualified name. If a shortName is provided then breeze will internally convert it to a qualified name by finding the first qualified name within the local metadataStore with a matching shortName.
Breeze metadata for each entity type can either be retrieved from a server or defined on the client. If defined on the client your entityType would be defined something like this:
myMetadataStore.addEntityType({
shortName: "RefactorColumn",
namespace: "Admin",
autoGeneratedKeyType: breeze.AutoGeneratedKeyType.Identity,
dataProperties: {
id: { dataType: DataType.Int32, isPartOfKey: true, isNullable: false },
// additional properties here:
},
});
There are several examples of this technique in the DocCode sample in the breeze.js.samples GitHub repo.
Alternatively, if you are defining metadata by returning json from the server you have two options, you can either return a valid OData metadata definition ( which it appears to be what you are trying to return above) OR you can use breeze's native metadata format, which is MUCH simpler. The simplest way to see what this would look like is to create the metadata on the client as shown above and the call
var exportedMetadata = myMetadataStore.exportMetadata();
The contents of the exportedMetadata will be in 'native' breeze metadata format, which is basically just a jsonified version of the internal entityType definition.
I have a REST API that returns, essentially a Map of (String, Object) where Object is either
A custom bean (let's say class Bean) or
A List of elements, all of type Bean
In JSON, this translates very well to:
{
"key1":{
"val1":"some string",
"val2":"some other string",
"val3":"another string"
},
"key2":[
{
"val1":"some string",
"val2":"some other string",
"val3":"another string"
},
{
"val1":"some string",
"val2":"some other string",
"val3":"another string"
}
]
}
Via swagger annotations, is there a way to specify this kind of a dynamic Map as the response class?
Thanks
I read the 'Open API Specification' - 'Add support for Map data types #38' page. As far as I understand, it recommends to use additionalProperties, but I haven't managed to make it work with Swagger UI 2.1.4 (see my related question: Swagger: map of string, Object).
I have found the following work-around: define an object, with one property that is the key, and with an inner object as the value for the "key" property.
The display in Swagger UI is correct, but one does not see it is a map, so it is then needed to explain in the comment that this is actually a map.
In your case, I find it a bit weird to have once a Bean, and once a list of Beans: I would find it more logical to have an array of one Bean in the first case.
Still, you could do, for example:
your_property: {
description: "This is a map that can contain several objects indexed by different keys. The value can be either a Bean or a list of Beans.",
type: object,
properties: {
key_for_single_bean: {
description: "The value associated to 'key_for_single_bean' is a single Bean",
$ref: "#/definitions/Bean"
},
key_for_list_of_beans: {
description: "The value associated to 'key_for_list_of_beans' is an array of Beans",
type: array,
items: {$ref: "#/definitions/Bean"}
}
}
}