Skip to content

Adding Luis swagger files. #1833

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
omarelhariry137 wants to merge 2 commits into from
Closed

Adding Luis swagger files. #1833

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
525a6bd
Adding Luis swagger files.
omar-el-hariry Oct 10, 2017
097fb60
Resolving semantic validation errors
omar-el-hariry Oct 19, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
268 changes: 268 additions & 0 deletions specification/cognitiveservices/data-plane/Luis/v2.0/LUIS Endpoint API.swagger.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,268 @@
{
"swagger": "2.0",
"info": {
"title": "LUIS Endpoint API",
"version": "1.0"
},
"x-ms-parameterized-host": {
"hostTemplate": "{AzureRegion}.api.cognitive.microsoft.com",
"parameters": [
{
"name": "AzureRegion",
"description": "Supported Azure regions for Cognitive Services endpoints",
"x-ms-parameter-location": "client",
"required": true,
"type": "string",
"in": "path",
"x-ms-skip-url-encoding": true,
"x-nullable": "false",
"x-ms-enum": {
"name": "AzureRegions",
"modelAsString": false
},
"enum": [
"westus",
"westeurope"
]
}
]
},
"basePath": "/luis/v2.0/apps",
"schemes": [
"https"
],
"securityDefinitions": {
"apiKeyHeader": {
"type": "apiKey",
"name": "Ocp-Apim-Subscription-Key",
"in": "header"
},
"apiKeyQuery": {
"type": "apiKey",
"name": "subscription-key",
"in": "query"
}
},
"security": [
{
"apiKeyHeader": []
},
{
"apiKeyQuery": []
}
],
"paths": {
"/{appId}": {
"get": {
"description": "Gets the published endpoint predictions for the given query",
"operationId": "v2.0 Response - Get predictions from endpoint",
Copy link
Copy Markdown
Contributor

@veronicagg veronicagg Oct 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

operationID should be of a form similar to https://github.com/Azure/azure-rest-api-specs/blob/current/specification/cognitiveservices/data-plane/Face/v1.0/Face.json#L31
The string before the underscore "_" groups the operations in a class named that way (in code generation)
Something like "Predictions_Get"
The name is used for the generated method name.

"parameters": [
{
"name": "appId",
"in": "path",
"description": "Format - guid. The application ID",
Copy link
Copy Markdown
Contributor

@veronicagg veronicagg Oct 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you may want to end each description with "."

"required": true,
"type": "string"
},
{
"name": "q",
"in": "query",
"description": "The query to predict",
"required": true,
"type": "string"
},
{
"name": "timezoneOffset",
"in": "query",
"description": "The timezone offset for the location of the request",
"type": "number"
},
{
"name": "verbose",
"in": "query",
"description": "If true will return all intents instead of just the topscoring intent",
"type": "boolean"
},
{
"name": "spellCheck",
"in": "query",
"description": "Enable spell checking",
"type": "boolean"
},
{
"name": "staging",
"in": "query",
"description": "Use staging endpoint",
"type": "boolean"
}
],
"responses": {
"200": {
"description": "A JSON object containing the predictions",
"examples": {
Copy link
Copy Markdown
Contributor

@veronicagg veronicagg Oct 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you could look into using x-ms-examples - https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md#why-x-ms-examples
It allows multiple examples and you can put the example in a separate file.

Copy link
Copy Markdown
Contributor

@veronicagg veronicagg Oct 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should there be a schema definition returned?
similar to https://github.com/Azure/azure-rest-api-specs/blob/current/specification/cognitiveservices/data-plane/Face/v1.0/Face.json#L52

"application/json": {
"query": "forward to frank 30 dollars through HSBC",
"topScoringIntent": {
"intent": "give",
"score": 0.3964121
},
"entities": [
{
"entity": "30",
"type": "builtin.number",
"startIndex": 17,
"endIndex": 18,
"resolution": {
"value": "30"
}
},
{
"entity": "frank",
"type": "frank",
"startIndex": 11,
"endIndex": 15,
"score": 0.935219169
},
{
"entity": "30 dollars",
"type": "builtin.currency",
"startIndex": 17,
"endIndex": 26,
"resolution": {
"unit": "Dollar",
"value": "30"
}
},
{
"entity": "hsbc",
"type": "Bank",
"startIndex": 36,
"endIndex": 39,
"resolution": {
"values": [
"BankeName"
]
}
}
]
}
}
}
},
"produces": [
"application/json"
]
},
"post": {
"description": "Gets the published endpoint prediction for the given long query",
"operationId": "v2.0 Response - Get predictions from endpoint (post)",
"parameters": [
{
"name": "appId",
Copy link
Copy Markdown
Contributor

@veronicagg veronicagg Oct 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if parameters are shared among operations you could define them in global section and refer them from here.
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameters-definitions-object
Make sure to include https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md#x-ms-parameter-location as needed.

"in": "path",
"description": "Format - guid. The application ID",
"required": true,
"type": "string"
},
{
"name": "timezoneOffset",
"in": "query",
"description": "The timezone offset for the location of the request",
"type": "number"
},
{
"name": "verbose",
"in": "query",
"description": "If true will return all intents instead of just the topscoring intent",
"type": "boolean"
},
{
"name": "spellCheck",
"in": "query",
"description": "Enable spell checking",
"type": "boolean"
},
{
"name": "staging",
"in": "query",
"description": "Use staging endpoint",
"type": "boolean"
},
{
"name": "q",
"in": "body",
"schema": {
"$ref": "#/definitions/Q"
},
"description": "The query to predict"
}
],
"consumes": [
"application/json"
],
"responses": {
"200": {
"description": "A JSON object containing the prediction",
"examples": {
"application/json": {
"query": "forward to frank 30 dollars through HSBC",
"topScoringIntent": {
"intent": "give",
"score": 0.3964121
},
"entities": [
{
"entity": "30",
"type": "builtin.number",
"startIndex": 17,
"endIndex": 18,
"resolution": {
"value": "30"
}
},
{
"entity": "frank",
"type": "frank",
"startIndex": 11,
"endIndex": 15,
"score": 0.935219169
},
{
"entity": "30 dollars",
"type": "builtin.currency",
"startIndex": 17,
"endIndex": 26,
"resolution": {
"unit": "Dollar",
"value": "30"
}
},
{
"entity": "hsbc",
"type": "Bank",
"startIndex": 36,
"endIndex": 39,
"resolution": {
"values": [
"BankeName"
]
}
}
]
}
}
}
},
"produces": [
"application/json"
]
}
}
},
"definitions": {
"Q": {
"type": "string",
"example": "\"forward to frank 30 dollars through HSBC\""
}
}
}
Loading