Commit d0427c7c authored by canterafonsj's avatar canterafonsj
Browse files

Swagger Open API description migrated

parent ecbf3c61
.DS_Store
#!/bin/bash
#
# Requires install swagger-cli: npm install -g swagger-cli
#
# Store current directory
current_dir=${PWD}
# Store script directory
script_directory="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
# Move cd to the script directory (the script must be called from the 'script' directory)
cd $script_directory
# Generate a file which combines all the spec files into a unique swagger definition file (maintains references)
swagger-cli bundle ../spec/ngsild_swagger.json -o combined_spec/ngsild_swagger_combined.json
# Generate a file which combines all the spec files into a unique swagger definition file (removes references)
swagger-cli bundle -r ../spec/ngsild_swagger.json -o combined_spec/ngsild_swagger_combined_dereferenced.json
# Move cd to the directory from where the script was called
cd $current_dir
{
"swagger": "2.0",
"info": {
"description": "This swagger file describes the NGSI-LD API defined by the ETSI ISG CIM group. This Cross-domain Context Information Management API allows to provide, consume and subscribe to context information in multiple scenarios and involving multiple stakeholders",
"version": "0.0.11",
"title": "ETSI ISG CIM / NGSI-LD API",
"termsOfService": "http://tbd.tbd/tbd/",
"contact": {
"email": "NGSI-LD@etsi.org"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"externalDocs": {
"description": "Find out more about the ETSI ISG Context Information Management",
"url": "https://portal.etsi.org/tb.aspx?tbid=854&SubTB=854"
},
"host": "tbd.tbd.tbd",
"basePath": "/v1",
"tags": [
{
"name": "ETSI",
"description": "European Telecommunications Standards Institute",
"externalDocs": {
"description": "Find out more",
"url": "http://www.etsi.org"
}
},
{
"name": "CIM",
"description": "Context Information Management",
"externalDocs": {
"description": "Find out more",
"url": "https://portal.etsi.org/tb.aspx?tbid=854&SubTB=854"
}
},
{
"name": "OMA",
"description": "Open Mobile Alliance",
"externalDocs": {
"description": "Find out more",
"url": "http://openmobilealliance.org"
}
},
{
"name": "NSGI",
"description": "Next Generation Service Interfaces",
"externalDocs": {
"description": "Find out more",
"url": "http://www.openmobilealliance.org/release/NGSI/V1_0-20120529-A/OMA-AD-NGSI-V1_0-20120529-A.pdf"
}
},
{
"name": "FIWARE NSGI v2",
"description": "FIWARE Next Generation Service Interfaces v2",
"externalDocs": {
"description": "Find out more",
"url": "https://orioncontextbroker.docs.apiary.io/#"
}
},
{
"name": "JSON-LD",
"description": "JSON for Linking Data",
"externalDocs": {
"description": "Find out more",
"url": "https://json-ld.org/"
}
},
{
"name": "NGSI-LD API",
"description": "API defined by the ETSI ISG CIM",
"externalDocs": {
"description": "Find out more",
"url": "http://www.etsi.org/deliver/etsi_gs/CIM/001_099/004/01.01.01_60/gs_CIM004v010101p.pdf"
}
}
],
"schemes": [
"http",
"https"
],
"paths": {
"/entities": {
"get": {
"description": "Retrieve a set of entities which matches a specific query from an NGSI-LD system",
"operationId": "queryEntities",
"parameters": [
{
"name": "id",
"description": "Comma separated list of URIs to be retrieved",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "type",
"description": "Comma separated list of Entity type names to be retrieved",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "idPattern",
"description": "Regular expression that must be matched by Entity ids",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "attrs",
"description": "Comma separated list of attribute names (properties or relationships) to be retrieved",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "q",
"description": "Query",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "georel",
"description": "Geo-relationship",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "geometry",
"description": "Geometry",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "coordinates",
"description": "Coordinates serialized as a string",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "geoproperty",
"description": "The name of the property that contains the geo-spatial data that will be used to resolve the geoquery",
"in": "query",
"required": false,
"type": "string"
}
],
"produces": [
"application/json",
"application/ld+json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/200/schema"
}
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/400/schema"
}
}
}
},
"post": {
"description": "Create a new Entity within an NGSI-LD system",
"operationId": "createEntity",
"parameters": [
{
"name": "EntityDescription",
"description": "Payload body in the request contains a JSON-LD object which represents the Entity that is to be created",
"in": "body",
"required": true,
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uri"
}
}
},
{
"$ref": "#/paths/~1entities~1%7BentityId%7D~1attrs/post/parameters/2/schema/allOf/1"
},
{
"$ref": "#/paths/~1entities~1%7BentityId%7D~1attrs/post/parameters/2/schema/allOf/2"
}
]
}
}
],
"consumes": [
"application/json",
"application/ld+json"
],
"responses": {
"201": {
"description": "Created. Contains the resource URI of the created Entity",
"schema": {
"type": "string"
}
},
"400": {
"description": "Bad request",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/400/schema"
}
},
"409": {
"description": "Already exists",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/400/schema"
}
},
"422": {
"description": "Unprocessable Entity",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/400/schema"
}
}
}
}
},
"/entities/{entityId}": {
"get": {
"description": "Retrieve an specific Entity from an NGSI-LD system. It's possible to specify the Entity attributes to be retrieved by using query parameters",
"operationId": "retrieveEntityById",
"parameters": [
{
"name": "entityId",
"description": "Id (URI) of the Entity to be retrieved",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "attrs",
"description": "Comma separated list of attribute names (properties or relationships) to be included in the response",
"in": "query",
"required": false,
"type": "string"
}
],
"produces": [
"application/json",
"application/ld+json"
],
"responses": {
"200": {
"description": "OK",
"schema": {
"allOf": [
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"format": "uri"
}
}
},
{
"$ref": "#/paths/~1entities~1%7BentityId%7D~1attrs/post/parameters/2/schema/allOf/1"
},
{
"$ref": "#/paths/~1entities~1%7BentityId%7D~1attrs/post/parameters/2/schema/allOf/2"
},
{
"$ref": "#/paths/~1csources~1%7BregistrationId%7D/get/responses/200/schema/allOf/1"
}
]
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string"
},
"detail": {
"type": "string"
}
}
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/400/schema"
}
}
}
},
"delete": {
"description": "Removes an specific Entity from an NGSI-LD system",
"operationId": "removeEntityById",
"parameters": [
{
"name": "entityId",
"description": "Id (URI) of the Entity to be removed",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"204": {
"description": "No Content. The entity was removed successfully"
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/400/schema"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/400/schema"
}
}
}
}
},
"/entities/{entityId}/attrs": {
"post": {
"description": "Append new Entity attributes to an existing Entity within an NGSI-LD system",
"operationId": "appendEntityAttrs",
"parameters": [
{
"name": "entityId",
"description": "Id (URI) of the Entity where to append new attributes",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "noOverwrite",
"description": "Indicates that no attribute overwrite shall be performed",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "EntityFragment",
"description": "Entity Fragment containing a complete representation of the attributes to be added",
"in": "body",
"required": true,
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D~1attrs/patch/parameters/1/schema"
}
}
],
"consumes": [
"application/json",
"application/ld+json"
],
"responses": {
"204": {
"description": "No Content. All the attributes were appended successfully"
},
"207": {
"description": "Multi-Status. Only the attributes included in the response payload were successfully appended",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D~1attrs/patch/responses/207/schema"
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/400/schema"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/400/schema"
}
}
}
},
"patch": {
"description": "Update existing Entity attributes within an NGSI-LD system",
"operationId": "updateEntityAttrs",
"parameters": [
{
"name": "entityId",
"description": "Id (URI) of the Entity where to update the specified attributes",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "EntityFragment",
"description": "Entity Fragment containing a complete representation of the attributes to be updated",
"in": "body",
"required": true,
"schema": {
"allOf": [
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"format": "uri"
}
}
},
{
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"minLength": 1
}
}
},
{
"allOf": [
{
"type": "object",
"properties": {
"location": {
"$ref": "#/paths/~1entities/post/parameters/0/schema/allOf/2/allOf/0/properties/observationSpace"
},
"observationSpace": {
"allOf": [
{
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"GeoProperty"
]
},
"value": {
"$ref": "#/paths/~1csources/post/parameters/0/schema/allOf/1/allOf/0/properties/location"
}
}
},
{
"type": "object",
"properties": {
"observedAt": {
"type": "string",
"format": "date-time"
}
}
}
]
},
"operationSpace": {
"$ref": "#/paths/~1entities/post/parameters/0/schema/allOf/2/allOf/0/properties/observationSpace"
}
}
},
{
"type": "object",
"properties": {
"@context": {
"type": [
"string",
"object",
"array"
]
}
}
}
]
}
]
}
}
],
"consumes": [
"application/json",
"application/ld+json"
],
"responses": {
"204": {
"description": "No Content. All the attributes were appended successfully"
},
"207": {
"description": "Multi-Status. Only the attributes included in the response payload were successfully appended",
"schema": {
"allOf": [
{
"$ref": "#/paths/~1entities~1%7BentityId%7D~1attrs/post/parameters/2/schema/allOf/1"
},
{
"$ref": "#/paths/~1entities~1%7BentityId%7D~1attrs/post/parameters/2/schema/allOf/2"
}
]
}
},
"400": {
"description": "Bad Request",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/400/schema"
}
},
"404": {
"description": "Not Found",
"schema": {
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/responses/400/schema"
}
}
}
}
},
"/entities/{entityId}/attrs/{attrId}": {
"patch": {
"description": "Update existing Entity attributes within an NGSI-LD system",
"operationId": "partialAttrUpdate",
"parameters": [
{
"name": "entityId",
"description": "Id (URI) of the Entity where to update the specified attribute",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "attrId",
"description": "Attribute name (property or relationship) to be updated",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "EntityFragment",
"description": "Entity Fragment containing the elements of the attribute to be updated",
"in": "body",