def get_class_details(global_: Dict[str, Any],
data: Dict[str, Any],
class_name: str,
path="") -> None:
"""
fetches details of class and adds the class to the dict along with the classDefinition until this point
:param global_: global state
:param class_name: name of class
:param data: data from the location given in $ref
:param path: Optional , custom enpoint to be assigned
:return: None
"""
doc = global_["doc"]
path = sanitise_path(path)
class_name = class_name
# we simply check if the class has been defined or not
if class_name not in global_["class_names"]:
desc = data
try:
classDefinition = HydraClass(class_name,
class_name,
desc["description"],
endpoint=True,
path=path)
except KeyError:
classDefinition = HydraClass(class_name,
class_name,
class_name,
endpoint=True,
path=path)
properties = data["properties"]
try:
required = data["required"]
except KeyError:
required = set()
for prop in properties:
# todo parse one more level to check 'type' and define class if needed
# check required from required list and add when true
flag = False
if prop in required and len(required) > 0:
flag = True
# TODO copy stuff from semantic ref branch regarding prop exists in
# definitionset or not
global_[class_name]["prop_definition"].append(
HydraClassProp("vocab:" + prop,
prop,
required=flag,
read=True,
write=True))
global_[class_name]["path"] = path
global_[class_name]["class_definition"] = classDefinition
global_["class_names"].add(class_name)
def get_class_details(class_location: List[str], doc: Dict["str",
Any]) -> None:
"""
fetches details of class and adds the class to the dict along with the classDefinition untill this point
:param class_location: location of class definition in the doc , we extract name from here
:param doc: the whole doc
:return:
"""
class_name = class_location[2]
# we simply check if the class has been defined or not
if class_name not in definitionSet:
try:
desc = doc[class_location[1]][class_location[2]]["description"]
except KeyError:
desc = class_location[2]
classDefinition = HydraClass(class_name,
class_name,
desc,
endpoint=True)
properties = doc[class_location[1]][class_location[2]]["properties"]
try:
required = doc[class_location[1]][class_location[2]]["required"]
except KeyError:
required = set()
for prop in properties:
# todo parse one more level to check 'type' and define class if needed
# check required from required list and add when true
flag = False
if prop in required and len(required) > 0:
flag = True
classDefinition.add_supported_prop(
HydraClassProp("vocab:" + prop,
prop,
required=flag,
read=True,
write=True))
classAndClassDefinition[class_name] = classDefinition
definitionSet.add(class_name)
else:
return
def createClass(entrypoint, class_dict):
"""Create HydraClass objects for classes in the API Documentation."""
# Base classes not used
exclude_list = [
'http://www.w3.org/ns/hydra/core#Resource',
'http://www.w3.org/ns/hydra/core#Collection', entrypoint["@id"]
]
id_ = class_dict["@id"]
if id_ in exclude_list:
return None, None
matchObj = re.match(r'vocab:(.*)', id_, re.M | re.I)
if matchObj:
id_ = matchObj.group(1)
# Syntax checks
try:
supportedProperty = class_dict["supportedProperty"]
except KeyError:
raise SyntaxError("Class must have [supportedProperty]")
try:
title = class_dict["title"]
except KeyError:
raise SyntaxError("Class must have [title]")
try:
desc = class_dict["description"]
except KeyError:
raise SyntaxError("Class must have [description]")
try:
supportedOperation = class_dict["supportedOperation"]
except KeyError:
raise SyntaxError("Class must have [supportedOperation]")
# See if class_dict is a Collection Class
collection = re.match(r'(.*)Collection(.*)', title, re.M | re.I)
if collection:
return None, None
# Check if class has it's own endpoint
endpoint = class_in_endpoint(class_dict, entrypoint)
# Check if class has a Collection
collection = collection_in_endpoint(class_dict, entrypoint)
# Create the HydraClass object
class_ = HydraClass(id_, title, desc, endpoint=endpoint)
# Add supportedProperty for the Class
for prop in supportedProperty:
prop_obj = createProperty(prop)
class_.add_supported_prop(prop_obj)
# Add supportedOperation for the Class
for op in supportedOperation:
op_obj = createOperation(op)
class_.add_supported_op(op_obj)
return class_, collection
def create_class(entrypoint: Dict[str, Any],
class_dict: Dict[str, Any]) -> Tuple[HydraClass, bool, str]:
"""Create HydraClass objects for classes in the API Documentation."""
# Base classes not used
exclude_list = [
'http://www.w3.org/ns/hydra/core#Resource',
'http://www.w3.org/ns/hydra/core#Collection', entrypoint["@id"]
]
id_ = class_dict["@id"]
if id_ in exclude_list:
return None, None, None
match_obj = re.match(r'vocab:(.*)', id_, re.M | re.I)
if match_obj:
id_ = match_obj.group(1)
doc_keys = {
"supportedProperty": False,
"title": False,
"description": False,
"supportedOperation": False
}
result = {}
for k, literal in doc_keys.items():
result[k] = input_key_check(class_dict, k, "class_dict", literal)
# See if class_dict is a Collection Class
# type: Union[Match[Any], bool]
collection = re.match(r'(.*)Collection(.*)', result["title"], re.M | re.I)
if collection:
return None, None, None
# Check if class has it's own endpoint
endpoint, path = class_in_endpoint(class_dict, entrypoint)
# Check if class has a Collection
collection, collection_path = collection_in_endpoint(
class_dict, entrypoint)
# Create the HydraClass object
class_ = HydraClass(id_,
result["title"],
result["description"],
path,
endpoint=endpoint)
# Add supportedProperty for the Class
for prop in result["supportedProperty"]:
prop_obj = create_property(prop)
class_.add_supported_prop(prop_obj)
# Add supportedOperation for the Class
for op in result["supportedOperation"]:
op_obj = create_operation(op)
class_.add_supported_op(op_obj)
return class_, collection, collection_path
def get_class_details(global_: Dict[str, Any],
data: Dict[str, Any],
class_name: str,
path="") -> None:
"""
fetches details of class and adds the class to the dict along with the
classDefinition until this point
:param global_: global state
:param class_name: name of class
:param data: data from the location given in $ref
:param path: Optional , custom enpoint to be assigned
:return: None
"""
doc = global_["doc"]
path = sanitise_path(path)
class_name = class_name
# we simply check if the class has been defined or not
if not hasattr(global_[class_name]["class_definition"], 'endpoint'):
desc = data
try:
classDefinition = HydraClass(class_name,
class_name,
desc["description"],
endpoint=True,
path=path)
except KeyError:
classDefinition = HydraClass(class_name,
class_name,
class_name,
endpoint=True,
path=path)
# we need to add object to global before we can attach props
added = generateOrUpdateClass(class_name, False, global_, "")
if added:
global_[class_name]["class_definition"] = classDefinition
properties = data["properties"]
try:
required = data["required"]
except KeyError:
required = set()
for prop in properties:
vocabFlag = True
errFlag = False
if prop not in global_["class_names"]:
try:
ref = properties[prop]["$ref"].split('/')
if ref[0] == "#":
get_class_details(
global_, get_data_at_location(ref, global_["doc"]),
get_class_name(ref), get_class_name(ref))
else:
vocabFlag = False
except KeyError:
# throw exception
# ERROR
errFlag = True
pass
except AttributeError:
# ERROR thow
pass
flag = False
if prop in required and len(required) > 0:
flag = True
if vocabFlag:
if errFlag:
global_[class_name]["prop_definition"].append(
HydraClassProp("",
prop,
required=flag,
read=True,
write=True))
else:
global_[class_name]["prop_definition"].append(
HydraClassProp("vocab:".format(prop),
prop,
required=flag,
read=True,
write=True))
else:
global_[class_name]["prop_definition"].append(
HydraClassProp(prop,
prop,
required=flag,
read=True,
write=True))
global_[class_name]["path"] = path
global_[class_name]["class_definition"] = classDefinition
global_["class_names"].add(class_name)
# Creating the HydraDoc object, this is the primary class for the Doc
API_NAME = "api" # Name of the API, will serve as EntryPoint
BASE_URL = "https://hydrus.com/" # The base url at which the API is hosted
# NOTE: The API will be accessible at BASE_URL + ENTRY_POINT
# (http://hydrus.com/api/)
# Create ApiDoc Object
api_doc = HydraDoc(API_NAME, "Title for the API Documentation",
"Description for the API Documentation", API_NAME, BASE_URL)
# Creating classes for the API
class_uri = "dummyClass" # URI of class for the HydraClass
class_title = "dummyClass" # Title of the Class
class_description = "A dummyClass for demo" # Description of the class
class_ = HydraClass(class_uri, class_title, class_description, endpoint=False)
# Class with single instance
class_2_uri = "singleClass"
class_2_title = "singleClass"
class_2_description = "A non collection class"
class_2 = HydraClass(class_2_uri,
class_2_title,
class_2_description,
endpoint=True)
# Another class with single instance, will be used as nested class
class_1_uri = "anotherSingleClass"
class_1_title = "anotherSingleClass"
class_1_description = "An another non collection class"
def doc_gen(API, BASE_URL):
"""Generate API Doc for server."""
# Main API Doc
api_doc = HydraDoc(API, "API Doc for the server side API",
"API Documentation for the server side system", API,
BASE_URL)
# State Class
state = HydraClass("State", "State", "Class for drone state objects")
# Properties
# Status include Active, Inactive, Off, Charging
state.add_supported_prop(
HydraClassProp("http://auto.schema.org/speed", "Speed", False, False,
True))
state.add_supported_prop(
HydraClassProp("http://schema.org/geo", "Position", False, False,
True))
state.add_supported_prop(
HydraClassProp("http://schema.org/Property", "Direction", False, False,
True))
state.add_supported_prop(
HydraClassProp("http://schema.org/fuelCapacity", "Battery", False,
False, True))
state.add_supported_prop(
HydraClassProp("https://schema.org/status", "Status", False, False,
True))
state.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
# Drone Class
drone = HydraClass("Drone", "Drone", "Class for a drone")
# Properties
drone.add_supported_prop(
HydraClassProp("vocab:State", "State", False, False, True))
drone.add_supported_prop(
HydraClassProp("http://schema.org/name", "name", False, False, True))
drone.add_supported_prop(
HydraClassProp("http://schema.org/model", "model", False, False, True))
drone.add_supported_prop(
HydraClassProp("http://auto.schema.org/speed", "MaxSpeed", False,
False, True))
drone.add_supported_prop(
HydraClassProp("http://schema.org/device", "Sensor", False, False,
True))
# Operations
# Drones will submit their state to the server at certain intervals or when some event happens
drone.add_supported_op(
HydraClassOp("SubmitDrone", "POST", "vocab:Drone", None,
[{
"statusCode": 200,
"description": "Drone updated"
}]))
drone.add_supported_op(
HydraClassOp("UpdateDrone", "PUT", "vocab:Drone", None,
[{
"statusCode": 200,
"description": "Drone updated"
}]))
# Mechanics or GUI need to get the drone, it contains the state object of the drone already.
drone.add_supported_op(
HydraClassOp("GetDrone", "GET", None, "vocab:Drone",
[{
"statusCode": 404,
"description": "Drone not found"
}, {
"statusCode": 200,
"description": "Drone Returned"
}]))
drone.add_supported_op(
HydraClassOp("DeleteDrone", "DELETE", None, None,
[{
"statusCode": 404,
"description": "Drone not found"
}, {
"statusCode": 200,
"description": "Drone successfully deleted."
}]))
# NOTE: Commands are stored in a collection. You may GET a command or you may DELETE it, there is not UPDATE.
command = HydraClass("Command", "Command", "Class for drone commands")
command.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
command.add_supported_prop(
HydraClassProp("vocab:State", "State", False, False, True))
# Used by mechanics to get newly added commands
command.add_supported_op(
HydraClassOp("GetCommand", "GET", None, "vocab:Command",
[{
"statusCode": 404,
"description": "Command not found"
}, {
"statusCode": 200,
"description": "Command Returned"
}]))
# Used by server to add new commands
command.add_supported_op(
HydraClassOp("AddCommand", "PUT", "vocab:Command", None,
[{
"statusCode": 201,
"description": "Command added"
}]))
# Data is stored as a collection. Each data object can be read.
# New data added to the collection
datastream = HydraClass("Datastream", "Datastream",
"Class for a datastream entry")
datastream.add_supported_prop(
HydraClassProp("http://schema.org/QuantitativeValue", "Temperature",
False, False, True))
datastream.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
datastream.add_supported_prop(
HydraClassProp("http://schema.org/geo", "Position", False, False,
True))
datastream.add_supported_op(
HydraClassOp("ReadDatastream", "GET", None, "vocab:Datastream",
[{
"statusCode": 404,
"description": "Data not found"
}, {
"statusCode": 200,
"description": "Data returned"
}]))
dronelog = HydraClass("DroneLog", "DroneLog",
"Class for a drone log entry")
dronelog.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
dronelog.add_supported_prop(
HydraClassProp("http://schema.org/Text", "LogString", False, False,
True))
dronelog.add_supported_op(
HydraClassOp("ReadDroneLog", "GET", None, "vocab:DroneLog",
[{
"statusCode": 404,
"description": "DroneLog not found"
}, {
"statusCode": 200,
"description": "DroneLog returned"
}]))
controllerlog = HydraClass("ControllerLog", "ControllerLog",
"Class for a controller log entry")
controllerlog.add_supported_prop(
HydraClassProp("http://schema.org/Text", "LogString", False, False,
True))
controllerlog.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
controllerlog.add_supported_op(
HydraClassOp("ReadControllerLog", "GET", None, "vocab:ControllerLog",
[{
"statusCode": 404,
"description": "ControllerLog not found"
}, {
"statusCode": 200,
"description": "ControllerLog returned"
}]))
httpapilog = HydraClass("HttpApiLog", "HttpApiLog",
"Class for a http api log entry")
httpapilog.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "Subject", False, False,
True))
httpapilog.add_supported_prop(
HydraClassProp("http://schema.org/Action", "Predicate", False, False,
True))
httpapilog.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "Object", False, False,
True))
httpapilog.add_supported_op(
HydraClassOp("ReadHttpApiLog", "GET", None, "vocab:HttpApiLog",
[{
"statusCode": 404,
"description": "HttpApiLog not found"
}, {
"statusCode": 200,
"description": "HttpApiLog returned"
}]))
# Single object representing the area of interest. No collections.
location = HydraClass("Location",
"Location",
"Class for location of the central controller.",
endpoint=True)
# Using two positions to have a bounding box
location.add_supported_prop(
HydraClassProp("http://schema.org/geo", "Location", False, False,
True))
# Allowing updation of the area of interest
location.add_supported_op(
HydraClassOp(
"UpdateLocation", "POST", "vocab:Location", None,
[{
"statusCode": 200,
"description": "Controller location updated successfully."
}]))
location.add_supported_op(
HydraClassOp(
"AddLocation", "PUT", "vocab:Location", None,
[{
"statusCode": 200,
"description": "Controller location added successfully."
}]))
location.add_supported_op(
HydraClassOp("GetLocation", "GET", None, "vocab:Location",
[{
"statusCode": 404,
"description": "Location of Controller not found."
}, {
"statusCode": 200,
"description": "Location of controller returned."
}]))
message = HydraClass("Message", "Message",
"Class for messages received by the GUI interface")
message.add_supported_prop(
HydraClassProp("http://schema.org/Text", "MessageString", False, False,
True))
message.add_supported_op(
HydraClassOp("GetMessage", "GET", None, "vocab:Message",
[{
"statusCode": 404,
"description": "Message not found"
}, {
"statusCode": 200,
"description": "Message returned"
}]))
message.add_supported_op(
HydraClassOp("DeleteMessage", "DELETE", None, None,
[{
"statusCode": 404,
"description": "Message not found"
}, {
"statusCode": 200,
"description": "Message successfully deleted."
}]))
anomaly = HydraClass(
"Anomaly", "Anomaly",
"Class for Temperature anomalies that need to be confirmed")
anomaly.add_supported_prop(
HydraClassProp("vocab:Location", "Location", False, False, True))
anomaly.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
# Status of any anomaly can be ["Positive", "Negative", "Confirming", "To be confirmed"]
anomaly.add_supported_prop(
HydraClassProp("http://schema.org/eventStatus", "Status", False, False,
True))
anomaly.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "AnomalyID", False,
False, True))
anomaly.add_supported_op(
HydraClassOp("GetAnomaly", "GET", None, "vocab:Anomaly",
[{
"statusCode": 404,
"description": "Anomaly not found"
}, {
"statusCode": 200,
"description": "Anomaly returned"
}]))
anomaly.add_supported_op(
HydraClassOp("AddAnomaly", "PUT", "vocab:Anomaly", None,
[{
"statusCode": 200,
"description": "Anomaly added successfully."
}]))
anomaly.add_supported_op(
HydraClassOp("UpdateAnomaly", "POST", "vocab:Anomaly", None,
[{
"statusCode": 201,
"description": "Anomaly updated successfully."
}]))
anomaly.add_supported_op(
HydraClassOp("DeleteAnomaly", "DELETE", None, None,
[{
"statusCode": 404,
"description": "Anomaly not found"
}, {
"statusCode": 200,
"description": "Anomaly successfully deleted."
}]))
api_doc.add_supported_class(drone, collection=True)
api_doc.add_supported_class(state, collection=False)
api_doc.add_supported_class(datastream, collection=True)
api_doc.add_supported_class(dronelog, collection=True)
api_doc.add_supported_class(controllerlog, collection=True)
api_doc.add_supported_class(httpapilog, collection=True)
api_doc.add_supported_class(location, collection=False)
api_doc.add_supported_class(command, collection=True)
api_doc.add_supported_class(message, collection=True)
api_doc.add_supported_class(anomaly, collection=True)
api_doc.add_baseResource()
api_doc.add_baseCollection()
api_doc.gen_EntryPoint()
return api_doc
def doc_gen(API, BASE_URL):
"""Generate API Doc for drone."""
# Main API Doc
api_doc = HydraDoc(API, "API Doc for the drone side API",
"API Documentation for the drone side system", API,
BASE_URL)
# State Class
# NOTE: Each drone will have only one State Class, this can't be deleted. Only read and update.
state = HydraClass("State", "State", "Class for drone state objects")
# Properties
state.add_supported_prop(
HydraClassProp("http://auto.schema.org/speed", "Speed", True, False,
False))
state.add_supported_prop(
HydraClassProp("http://schema.org/geo", "Position", True, False,
False))
state.add_supported_prop(
HydraClassProp("http://schema.org/Property", "Direction", True, False,
False))
state.add_supported_prop(
HydraClassProp("http://schema.org/fuelCapacity", "Battery", True, True,
False))
state.add_supported_prop(
HydraClassProp("https://schema.org/status", "SensorStatus", True,
False, False))
# Drone Class
# NOTE: The actual changes to the drone are to be made at the /api/Drone URI.
# GET will return current State. POST will update the State.
drone = HydraClass("Drone", "Drone", "Class for a drone", endpoint=True)
# Properties
drone.add_supported_prop(
HydraClassProp("vocab:State", "DroneState", False, False, True))
drone.add_supported_prop(
HydraClassProp("http://schema.org/name", "name", False, False, True))
drone.add_supported_prop(
HydraClassProp("http://schema.org/model", "model", False, False, True))
drone.add_supported_prop(
HydraClassProp("http://auto.schema.org/speed", "MaxSpeed", False,
False, True))
drone.add_supported_prop(
HydraClassProp("http://schema.org/device", "Sensor", False, False,
True))
drone.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
# Operations
drone.add_supported_op(
HydraClassOp("GetDrone", "GET", None, "vocab:Drone",
[{
"statusCode": 404,
"description": "Drone not found"
}, {
"statusCode": 200,
"description": "Drone returned"
}]))
# When new commands are issued, mechanics will need to change the state of the drone
drone.add_supported_op(
HydraClassOp("UpdateDrone", "POST", "vocab:Drone", None,
[{
"statusCode": 200,
"description": "Drone updated"
}]))
# Command Class
# NOTE: Commands are stored in a collection. You may GET a command or you may DELETE it, there is not UPDATE.
command = HydraClass("Command", "Command", "Class for drone commands")
command.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
command.add_supported_prop(
HydraClassProp("vocab:State", "State", False, False, True))
# Used by mechanics to get newly added commands
command.add_supported_op(
HydraClassOp("GetCommand", "GET", None, "vocab:Command",
[{
"statusCode": 404,
"description": "Command not found"
}, {
"statusCode": 200,
"description": "Command Returned"
}]))
# Used by server to add new commands
command.add_supported_op(
HydraClassOp("AddCommand", "PUT", "vocab:Command", None,
[{
"statusCode": 201,
"description": "Command added"
}]))
# Used by mechanics to delete command after it has been executed
command.add_supported_op(
HydraClassOp("DeleteCommand", "DELETE", None, None,
[{
"statusCode": 200,
"description": "Command deleted"
}]))
# Data class
# NOTE: This is for the Data to be captured/generated. The mechanics module will enter random data and POST it.
# The server will read[GET] the data when it needs it. No need for collections. Only one instance showing current reading of sensor
# The URI is /api/Data
datastream = HydraClass("Datastream",
"Datastream",
"Class for a data entry from drone sensors",
endpoint=True)
datastream.add_supported_prop(
HydraClassProp("http://schema.org/QuantitativeValue", "Temperature",
False, False, True))
datastream.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
datastream.add_supported_prop(
HydraClassProp("http://schema.org/geo", "Position", False, False,
True))
datastream.add_supported_op(
HydraClassOp("GetDatastream", "GET", None, "vocab:Datastream",
[{
"statusCode": 404,
"description": "Datastream not found"
}, {
"statusCode": 200,
"description": "Datastream returned"
}]))
datastream.add_supported_op(
HydraClassOp("UpdateDatastream", "POST", "vocab:Datastream", None,
[{
"statusCode": 200,
"description": "Datastream updated"
}]))
api_doc.add_supported_class(state, collection=False)
api_doc.add_supported_class(drone, collection=False)
api_doc.add_supported_class(command, collection=True)
api_doc.add_supported_class(datastream, collection=False)
api_doc.add_baseCollection()
api_doc.add_baseResource()
api_doc.gen_EntryPoint()
return api_doc
def doc_gen(API, BASE_URL):
"""Generate API Doc for server."""
# Main API Doc
api_doc = HydraDoc(API, "API Doc for the server side API",
"API Documentation for the server side system", API,
BASE_URL)
# State Class
state = HydraClass("State", "State", "Class for drone state objects")
# Properties
state.add_supported_prop(
HydraClassProp("http://auto.schema.org/speed", "Speed", False, False,
True))
state.add_supported_prop(
HydraClassProp("http://schema.org/geo", "Position", False, False,
True))
state.add_supported_prop(
HydraClassProp("http://schema.org/Property", "Direction", False, False,
True))
state.add_supported_prop(
HydraClassProp("http://schema.org/fuelCapacity", "Battery", False,
False, True))
state.add_supported_prop(
HydraClassProp("https://schema.org/status", "SensorStatus", False,
False, True))
state.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
# Drone Class
drone = HydraClass("Drone", "Drone", "Class for a drone")
# Properties
drone.add_supported_prop(
HydraClassProp("vocab:State", "DroneState", False, False, True))
drone.add_supported_prop(
HydraClassProp("http://schema.org/name", "name", False, False, True))
drone.add_supported_prop(
HydraClassProp("http://schema.org/model", "model", False, False, True))
drone.add_supported_prop(
HydraClassProp("http://auto.schema.org/speed", "MaxSpeed", False,
False, True))
drone.add_supported_prop(
HydraClassProp("http://schema.org/device", "Sensor", False, False,
True))
# Operations
# Drones will submit their state to the server at certain intervals or when some event happens
drone.add_supported_op(
HydraClassOp("SubmitDrone", "POST", "vocab:Drone", None,
[{
"statusCode": 200,
"description": "Drone updated"
}]))
drone.add_supported_op(
HydraClassOp("CreateDrone", "PUT", "vocab:Drone", None,
[{
"statusCode": 200,
"description": "Drone added"
}]))
drone.add_supported_op(
HydraClassOp("GetDrone", "GET", None, "vocab:Drone",
[{
"statusCode": 404,
"description": "Drone not found"
}, {
"statusCode": 200,
"description": "Drone Returned"
}]))
# NOTE: Commands are stored in a collection. You may GET a command or you may DELETE it, there is not UPDATE.
command = HydraClass("Command", "Command", "Class for drone commands")
command.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
command.add_supported_prop(
HydraClassProp("vocab:State", "State", False, False, True))
# Used by mechanics to get newly added commands
command.add_supported_op(
HydraClassOp("GetCommand", "GET", None, "vocab:Command",
[{
"statusCode": 404,
"description": "Command not found"
}, {
"statusCode": 200,
"description": "Command Returned"
}]))
# Used by server to add new commands
command.add_supported_op(
HydraClassOp("AddCommand", "PUT", "vocab:Command", None,
[{
"statusCode": 201,
"description": "Command added"
}]))
command.add_supported_op(
HydraClassOp("DeleteCommand", "DELETE", None, None,
[{
"statusCode": 201,
"description": "Command deleted"
}]))
# Logs to be accessed mostly by the GUI. Mechanics should add logs for every event.
log = HydraClass("LogEntry", "LogEntry", "Class for a log entry")
# Subject
log.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", True, True,
False))
# Predicate
log.add_supported_prop(
HydraClassProp("http://schema.org/UpdateAction", "Update", False, True,
False))
log.add_supported_prop(
HydraClassProp("http://schema.org/ReplyAction", "Get", False, True,
False))
log.add_supported_prop(
HydraClassProp("http://schema.org/SendAction", "Send", False, True,
False))
# Objects
log.add_supported_prop(
HydraClassProp("vocab:State", "State", False, True, False))
log.add_supported_prop(
HydraClassProp("vocab:Datastream", "Data", False, True, False))
log.add_supported_prop(
HydraClassProp("vocab:Command", "Command", False, True, False))
# GUI will get a certain log entry.
log.add_supported_op(
HydraClassOp("GetLog", "GET", None, "vocab:LogEntry",
[{
"statusCode": 404,
"description": "Log entry not found"
}, {
"statusCode": 200,
"description": "Log entry returned"
}]))
log.add_supported_op(
HydraClassOp("AddLog", "PUT", "vocab:LogEntry", None,
[{
"statusCode": 201,
"description": "Log entry created"
}]))
# Data is stored as a collection. Each data object can be read.
# New data added to the collection
datastream = HydraClass("Datastream", "Datastream",
"Class for a datastream entry")
datastream.add_supported_prop(
HydraClassProp("http://schema.org/QuantitativeValue", "Temperature",
False, False, True))
datastream.add_supported_prop(
HydraClassProp("http://schema.org/identifier", "DroneID", False, False,
True))
datastream.add_supported_prop(
HydraClassProp("http://schema.org/geo", "Position", False, False,
True))
datastream.add_supported_op(
HydraClassOp("ReadDatastream", "GET", None, "vocab:Datastream",
[{
"statusCode": 404,
"description": "Data not found"
}, {
"statusCode": 200,
"description": "Data returned"
}]))
datastream.add_supported_op(
HydraClassOp("UpdateDatastream", "POST", "vocab:Datastream", None,
[{
"statusCode": 200,
"description": "Data updated"
}]))
datastream.add_supported_op(
HydraClassOp("DeleteDatastream", "DELETE", None, None,
[{
"statusCode": 200,
"description": "Data deleted"
}]))
# Single object representing the area of interest. No collections.
area = HydraClass("Area",
"Area",
"Class for Area of Interest of the server",
endpoint=True)
# Using two positions to have a bounding box
area.add_supported_prop(
HydraClassProp("http://schema.org/geo", "TopLeft", False, False, True))
area.add_supported_prop(
HydraClassProp("http://schema.org/geo", "BottomRight", False, False,
True))
# Allowing updation of the area of interest
area.add_supported_op(
HydraClassOp("UpdateArea", "POST", "vocab:Area", None,
[{
"statusCode": 200,
"description": "Area of interest changed"
}]))
area.add_supported_op(
HydraClassOp("GetArea", "GET", None, "vocab:Area",
[{
"statusCode": 404,
"description": "Area of interest not found"
}, {
"statusCode": 200,
"description": "Area of interest returned"
}]))
message = HydraClass("Message", "Message",
"Class for messages received by the GUI interface")
message.add_supported_prop(
HydraClassProp("http://schema.org/Text", "MessageString", False, False,
True))
message.add_supported_op(
HydraClassOp("GetMessage", "GET", None, "vocab:Message",
[{
"statusCode": 404,
"description": "Message not found"
}, {
"statusCode": 200,
"description": "Message returned"
}]))
message.add_supported_op(
HydraClassOp("DeleteMessage", "DELETE", None, None,
[{
"statusCode": 200,
"description": "Message deleted"
}]))
api_doc.add_supported_class(drone, collection=True)
api_doc.add_supported_class(state, collection=False)
api_doc.add_supported_class(datastream, collection=True)
api_doc.add_supported_class(log, collection=True)
api_doc.add_supported_class(area, collection=False)
api_doc.add_supported_class(command, collection=True)
api_doc.add_supported_class(message, collection=True)
api_doc.add_baseResource()
api_doc.add_baseCollection()
api_doc.gen_EntryPoint()
return api_doc
from hydrus.hydraspec.doc_writer import HydraDoc, HydraClass, HydraClassProp, HydraClassOp
from typing import Any, Dict, Union
"""Creating the HydraDoc object, this is the primary class for the Doc"""
API_NAME = "api" # Name of the API, will serve as EntryPoint
BASE_URL = "https://hydrus.com/" # The base url at which the API is hosted
# NOTE: The API will be accessible at BASE_URL + ENTRY_POINT (http://hydrus.com/api/)
api_doc = HydraDoc(API_NAME, "Title for the API Documentation",
"Description for the API Documentation", API_NAME, BASE_URL)
"""Creating classes for the API"""
class_uri = "dummyClass" # URI of class for the HydraClass
class_title = "dummyClass" # Title of the Class
class_description = "A dummyClass for demo" # Description of the class
class_ = HydraClass(class_uri, class_title, class_description, endpoint=False)
# NOTE: Setting endpoint=True creates an endpoint for the class itself, this is usually for classes that have single instances.
# These classes should not ideally have a Collection, although Hydrus will allow creation of Collections for them
"""Create new properties for the class"""
prop1_uri = "http://props.hydrus.com/prop1" # The URI of the class of the property
prop1_title = "Prop1" # Title of the property
dummyProp1 = HydraClassProp(prop1_uri,
prop1_title,
required=False,
read=False,
write=True)
prop2_uri = "http://props.hydrus.com/prop2"
prop2_title = "Prop2"
