def create_operation(supported_op: Dict[str, Any]) -> HydraClassOp:
"""Create a HyraClassOp object from the supportedOperation."""
# Syntax checks
doc_keys = {
"title": False,
"method": False,
"expects": True,
"returns": True,
"expectsHeader": False,
"returnsHeader": False,
"possibleStatus": False
}
result = {}
for k, literal in doc_keys.items():
result[k] = input_key_check(supported_op, k, "supported_op", literal)
possible_statuses = list()
for status in result["possibleStatus"]:
status_obj = create_status(status)
possible_statuses.append(status_obj)
# Create the HydraClassOp object
op_ = HydraClassOp(result["title"], result["method"], result["expects"],
result["returns"], result["expectsHeader"],
result["returnsHeader"], possible_statuses)
return op_
def get_ops(global_: Dict[str, Any], path: str,
method: Dict[str, Any], class_name: str) -> None:
"""
Get operations from path object and store in global path
:param global_: global state
:param path: endpoint
:param method: method block
:param class_name:class name
"""
if method not in global_[class_name]["methods"]:
op_method = method
op_expects = None
op_name = try_catch_replacement(
global_["doc"]["paths"][path][method],
"summary",
class_name)
op_status = list()
op_expects = get_parameters(global_, path, method, class_name)
try:
responses = global_["doc"]["paths"][path][method]["responses"]
op_returns = None
for response in responses:
if response != 'default':
op_status.append({"statusCode": int(
response),
"description": responses[response]["description"]})
try:
op_returns = "vocab:{}".format(
responses[response]["schema"]["$ref"].split('/')[2])
except KeyError:
pass
if op_returns is None:
try:
op_returns = "vocab:{}".format(
responses[response]["schema"]["items"]["$ref"].split('/')[2])
except KeyError:
op_returns = try_catch_replacement(
responses[response]["schema"], "type", None)
except KeyError:
op_returns = None
if len(op_status) == 0:
op_status.append(
{"statusCode": 200, "description": "Successful Operation"})
global_[class_name]["methods"].add(method)
global_[class_name]["op_definition"].append(HydraClassOp(
op_name, op_method.upper(), op_expects, op_returns, op_status))
else:
print("Method on path {} already present !".format(path))
def create_operation(supported_operation: Dict[str, Any]) -> HydraClassOp:
"""
Creates the instance of HydraClassOp
:param supported_operation: The expanded supported operation from the API DOC
:return: HydraClassOp
"""
op_title = "The title of the operation"
op_expects = "null"
op_returns = "null"
op_expects_header = []
op_returns_header = []
op_possible_status = []
if hydra['title'] in supported_operation:
op_title = supported_operation[hydra['title']][0]['@value']
op_method = supported_operation[hydra['method']][0]['@value']
if hydra['expects'] in supported_operation:
op_expects = check_namespace(
supported_operation[hydra['expects']][0]['@id'])
if hydra['returns'] in supported_operation:
op_returns = check_namespace(
supported_operation[hydra['returns']][0]['@id'])
if hydra['expectsHeader'] in supported_operation:
for header in supported_operation[hydra['expectsHeader']]:
op_expects_header.append(header['@value'])
if hydra['returnsHeader'] in supported_operation:
for header in supported_operation[hydra['returnsHeader']]:
op_returns_header.append(header['@value'])
if hydra['possibleStatus'] in supported_operation:
op_possible_status = create_status(
supported_operation[hydra['possibleStatus']])
op_ = HydraClassOp(title=op_title,
method=op_method,
expects=op_expects,
returns=op_returns,
expects_header=op_expects_header,
returns_header=op_returns_header,
possible_status=op_possible_status)
return op_
# NOTE: Properties that are required=True must be added during class object creation
# Properties that are read=True are read only
# Properties that are write=True are writable
# Create operations for the class
op_name = "UpdateClass" # The name of the operation
op_method = "POST" # The method of the Operation [GET, POST, PUT, DELETE]
# URI of the object that is expected for the operation
op_expects = class_.id_
op_returns = None # URI of the object that is returned by the operation
op_returns_header = ["Content-Type", "Content-Length"]
op_expects_header = []
# List of statusCode for the operation
op_status = [HydraStatus(code=200, desc="dummyClass updated.")]
op1 = HydraClassOp(op_name, op_method, op_expects, op_returns,
op_expects_header, op_returns_header, op_status)
# Same way add DELETE, PUT and GET operations
op2_status = [HydraStatus(code=200, desc="dummyClass deleted.")]
op2 = HydraClassOp("DeleteClass", "DELETE", None, None, [], [], op2_status)
op3_status = [HydraStatus(code=201, desc="dummyClass successfully added.")]
op3 = HydraClassOp("AddClass", "PUT", class_.id_, None, [], [], op3_status)
op4_status = [HydraStatus(code=200, desc="dummyClass returned.")]
op4 = HydraClassOp("GetClass", "GET", None, class_.id_, [], [], op4_status)
# Operations for non collection class
class_2_op1_status = [HydraStatus(code=200, desc="singleClass changed.")]
class_2_op1 = HydraClassOp("UpdateClass", "POST", class_2.id_, None, [], [],
class_2_op1_status)
class_2_op2_status = [HydraStatus(code=200, desc="singleClass deleted.")]
class_2_op2 = HydraClassOp("DeleteClass", "DELETE", None, None, [], [],
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))
state.add_supported_op(
HydraClassOp("GetState", "GET", None, "vocab:State",
[{
"statusCode": 404,
"description": "State not found"
}, {
"statusCode": 200,
"description": "State Returned"
}]))
# 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=True)
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
read=False,
write=True)
# NOTE: Properties that are required=True must be added during class object creation
# Properties that are read=True are read only
# Properties that are write=True are writable
# Create operations for the class
op_name = "UpdateClass" # The name of the operation
op_method = "POST" # The method of the Operation [GET, POST, PUT, DELETE]
# URI of the object that is expected for the operation
op_expects = "vocab:dummyClass"
op_returns = None # URI of the object that is returned by the operation
# List of statusCode for the operation
op_status = [{"statusCode": 200, "description": "dummyClass updated"}]
op1 = HydraClassOp(op_name, op_method, op_expects, op_returns, op_status)
# Same way add DELETE, PUT and GET operations
op2_status = [{"statusCode": 200, "description": "dummyClass deleted"}]
op2 = HydraClassOp("DeleteClass", "DELETE", None, None, op2_status)
op3_status = [{
"statusCode": 201,
"description": "dummyClass successfully added"
}]
op3 = HydraClassOp("AddClass", "PUT", "vocab:dummyClass", None, op3_status)
op4_status = [{"statusCode": 200, "description": "dummyClass returned"}]
op4 = HydraClassOp("GetClass", "GET", None, "vocab:dummyClass", op4_status)
# Operations for non collection class
class_2_op1_status = [{
"statusCode": 200,
def doc_gen(API: str, BASE_URL: str) -> HydraDoc:
"""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))
# Operations
state.add_supported_op(
HydraClassOp("GetState", "GET", None, "vocab:State",
[{
"statusCode": 404,
"description": "State not found"
}, {
"statusCode": 200,
"description": "State Returned"
}]))
# 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=True)
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