Skip to content
GitLab
Commit 8ef715db authored by Giuseppe Tropea's avatar Giuseppe Tropea
Browse files

Merge branch 'fix-spec' from Stefan into 'master', makes the OpenAPI spec usable again 

Fix spec

See merge request !7
parents 5a9b241b 18e91b13
Pipeline #6376 passed with stages
in 7 seconds
Show whitespace changes
Inline Side-by-side
.gitlab-ci.yml
View file @ 8ef715db
# This file is a template, and might need editing before it works on your project.
# Official framework image. Look for the different tagged releases at:
# https://hub.docker.com/r/library/node/tags/
image: node::13.7-alpine
# This folder is cached between builds
# http://docs.rep.com/ce/ci/yaml/README.html#cache
cache:
paths:
- node_modules/
before_script:
- yarn
- docker info
stages:
- prepare
- test
build:
stage: prepare
image: docker:19.03.12
script:
- scripts/setBasePath.sh https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/raw/master http://localhost:8080
- docker build -t ngsi-local -f docker/Dockerfile .
allow_failure: false
test:
stage: test
image: docker:19.03.12
services:
- ngsi-local
script:
- echo "Running tests..."
- yarn test
allow_failure: true
- echo ${TEST}
- scripts/setBasePath.sh https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/raw/master http://localhost:9090
- docker run --network host -i -v ${PWD}/:/data wistefan/redocly-openapi-cli bundle /data/spec/updated/ngsi-ld-spec-open-api.json -o /data/spec/updated/generated/full_api.json
- docker run --network host --rm -v ${PWD}/:/local openapitools/openapi-generator-cli validate -i /local/spec/updated/generated/full_api.json
allow_failure: false
# TODO: after gitlab update, the ci should publish the bundled api
README.md
View file @ 8ef715db
......@@ -10,10 +10,29 @@ This repository contains OpenAPI descriptions for the NGSI-LD interface defined
To get an account on ETSI Forge and to learn how to contribute visit the [Forge Getting started wiki](https://forge.etsi.org/wiki/index.php/Get_started).
More info @ [CONTIBUTE](./CONTRIBUTE.md)
More info @ [CONTRIBUTE](./CONTRIBUTE.md)
Change requests are managed using [Gerrit](https://forge.etsi.org/gerrit).
### Local editing
>:warning: The described setup requires [docker](https://docs.docker.com/engine/install/) to be installed.
In order to edit the api locally, the script [runLocalDevEnv.sh](scripts/runLocalDevEnv.sh) can be used. When executed from the root of this repository,
it replaces all paths to the master branch inside [spec](spec) and [schema](schema) and serves them through a local file-server. Without that, all
references are resolved with 'https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/raw/master' and therefore changes will not be present locally.
With the local file-server still running, you can build the bundled api via:
```
docker run --network host -it -v ${PWD}/:/data wistefan/redocly-openapi-cli bundle /data/spec/updated/ngsi-ld-spec-open-api.json -o /data/spec/updated/generated/full_api.json
```
And validate it with:
```
docker run --network host --rm -v ${PWD}/:/local openapitools/openapi-generator-cli validate -i /local/spec/updated/generated/full_api.json
```
When editing is finished, hit the enter button on your local dev env and push.
## Report issues
To report issues, bugs or requests please fill in a bug [at this location](https://forge.etsi.org/bugzilla/enter_bug.cgi?product=NGSI-LD).
......
bundle/ngsild_swagger_combined.json deleted 100644 → 0
View file @ 5a9b241b
{
"openapi": "3.0.3",
"info": {
"description": "This OAS 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": "latest",
"title": "ETSI ISG CIM / NGSI-LD API",
"contact": {
"email": "NGSI-LD@etsi.org"
}
},
"externalDocs": {
"description": "Find out more about the ETSI ISG Context Information Management",
"url": "https://portal.etsi.org/tb.aspx?tbid=854&SubTB=854"
},
"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": "JSON-LD",
"description": "JSON for Linked 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": "Preliminary Specification",
"url": "http://www.etsi.org/deliver/etsi_gs/CIM/001_099/004/01.01.01_60/gs_CIM004v010101p.pdf"
}
}
],
"paths": {
"/entities/": {
"get": {
"description": "Retrieve a set of entities which matches a specific query from an NGSI-LD system",
"operationId": "queryEntities",
"tags": [
"Context Information"
],
"parameters": [
{
"name": "id",
"description": "Comma separated list of URIs to be retrieved",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "idPattern",
"description": "Regular expression that must be matched by Entity ids",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "regexp"
}
},
{
"name": "type",
"description": "Comma separated list of Entity type names to be retrieved",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "attrs",
"description": "Comma separated list of attribute names (properties or relationships) to be retrieved",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "q",
"description": "Query",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "georel",
"description": "Geo-relationship",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"enum": [
"equals",
"disjoint",
"intersects",
"within",
"contains",
"overlaps"
]
},
{
"type": "string",
"pattern": "^near;((maxDistance==\\d+)|(minDistance==\\d+))$"
}
]
}
},
{
"name": "geometry",
"description": "Geometry",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"Point",
"MultiPoint",
"LineString",
"MultiLineString",
"Polygon",
"MultiPolygon"
]
}
},
{
"name": "coordinates",
"description": "Coordinates serialized as a string",
"in": "query",
"required": false,
"schema": {
"oneOf": [
{
"$ref": "#/paths/~1csourceRegistrations~1/get/responses/200/content/application~1json%3Bapplication~1ld%2Bjson/schema/items/allOf/0/properties/location/definitions/position"
},
{
"$ref": "#/paths/~1csourceRegistrations~1/get/responses/200/content/application~1json%3Bapplication~1ld%2Bjson/schema/items/allOf/0/properties/location/definitions/positionArray"
},
{
"$ref": "#/paths/~1csourceRegistrations~1/get/responses/200/content/application~1json%3Bapplication~1ld%2Bjson/schema/items/allOf/0/properties/location/definitions/lineString"
},
{
"$ref": "#/paths/~1csourceRegistrations~1/get/responses/200/content/application~1json%3Bapplication~1ld%2Bjson/schema/items/allOf/0/properties/location/definitions/polygon"
}
]
}
},
{
"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,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "csf",
"description": "Context Source Filter",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "limit",
"description": "Pagination limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1
}
},
{
"name": "options",
"description": "Options dictionary",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"keyValues",
"sysAttrs"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json;application/ld+json": {
"schema": {
"$ref": "#/paths/~1entityOperations~1create/post/requestBody/content/application~1json%3Bapplication~1ld%2Bjson/schema"
},
"examples": {
"simple": {
"externalValue": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/examples/EntityList-example.json"
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json;application/ld+json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string"
},
"detail": {
"type": "string"
}
},
"required": [
"type"
]
}
}
}
}
}
},
"post": {
"description": "Create a new Entity within an NGSI-LD system",
"operationId": "createEntity",
"tags": [
"Context Information"
],
"requestBody": {
"required": true,
"content": {
"application/json;application/ld+json": {
"schema": {
"allOf": [
{
"required": [
"id",
"type"
]
},
{
"$ref": "#/paths/~1entities~1%7BentityId%7D~1attrs~1/post/requestBody/content/application~1json%3Bapplication~1ld%2Bjson/schema"
}
]
}
}
}
},
"responses": {
"201": {
"description": "Created. Contains the resource URI of the created Entity"
},
"400": {
"description": "Bad request",
"content": {
"application/json;application/ld+json": {
"schema": {
"$ref": "#/paths/~1entities~1/get/responses/400/content/application~1json%3Bapplication~1ld%2Bjson/schema"
}
}
}
},
"409": {
"description": "Already exists",
"content": {
"application/json;application/ld+json": {
"schema": {
"$ref": "#/paths/~1entities~1/get/responses/400/content/application~1json%3Bapplication~1ld%2Bjson/schema"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json;application/ld+json": {
"schema": {
"$ref": "#/paths/~1entities~1/get/responses/400/content/application~1json%3Bapplication~1ld%2Bjson/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",
"tags": [
"Context Information"
],
"parameters": [
{
"name": "entityId",
"description": "Entity Id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "attrs",
"description": "Comma separated list of attribute names (properties or relationships) to be retrieved",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1
}
},
{
"name": "type",
"description": "Entity Type",
"in": "query",
"required": false,
"schema": {
"$ref": "#/paths/~1temporal~1entities~1/get/parameters/10/schema"
}
},
{
"name": "options",
"description": "Options dictionary",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"keyValues",
"sysAttrs"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json;application/ld+json": {
"schema": {
"$ref": "#/paths/~1entities~1/post/requestBody/content/application~1json%3Bapplication~1ld%2Bjson/schema"
},
"examples": {
"simple": {
"externalValue": "https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/examples/Entity-example.json"
}
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json;application/ld+json": {
"schema": {
"$ref": "#/paths/~1entities~1/get/responses/400/content/application~1json%3Bapplication~1ld%2Bjson/schema"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json;application/ld+json": {
"schema": {
"$ref": "#/paths/~1entities~1/get/responses/400/content/application~1json%3Bapplication~1ld%2Bjson/schema"
}
}
}
}
}
},
"delete": {
"description": "Removes an specific Entity from an NGSI-LD system",
"operationId": "removeEntityById",
"tags": [
"Context Information"
],
"parameters": [
{
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/parameters/0"
},
{
"$ref": "#/paths/~1entities~1%7BentityId%7D/get/parameters/2"
}
],
"responses": {
"204": {
"description": "No Content. The entity was removed successfully"
},
"400": {
"description": "Bad Request",
"content": {
"application/json;application/ld+json": {
"schema": {
"$ref": "#/paths/~1entities~1/get/responses/400/content/application~1json%3Bapplication~1ld%2Bjson/schema"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json;application/ld+json": {
"schema": {
"$ref": "#/paths/~1entities~1/get/responses/400/content/application~1json%3Bapplication~1ld%2Bjson/schema"
}
}
}
}
}
}
},
"/entities/{entityId}/attrs/": {
"post": {
"description": "Append new Entity attributes to an existing Entity within an NGSI-LD system",
"operationId": "appendEntityAttrs",
"tags": [
"Context Information"
],
"parameters": [
{
"name": "entityId",
"description": "Entity Id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uri"
}
},
{
"name": "options",
"description": "Indicates that no attribute overwrite shall be performed",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"noOverwrite"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json;application/ld+json": {
"schema": {
"type": "object",
"properties": {
"@context": {
"anyOf": [
{
"type": "object"
},
{
"type": "string",
"format": "uri"
},
{
"type": "array",
"minItems": 1,
"items": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "object"
}
]
}
}
]
},
"location": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "GeoProperty"
},
"value": {
"$ref": "#/paths/~1csourceRegistrations~1/get/responses/200/content/application~1json%3Bapplication~1ld%2Bjson/schema/items/allOf/0/properties/location"
},
"observedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"$ref": "#/paths/~1entities~1%7BentityId%7D~1attrs~1/post/requestBody/content/application~1json%3Bapplication~1ld%2Bjson/schema/properties/createdAt"