Writer

[chrizandr]

New and (hopefully) compete API Doc writer. Here's a little demo about the usage of the writer.

The API Doc is an object of the HydraDoc class. HydraDoc attributes:

• API : contains the API name/address of the server
• base_url : contains the base_url of the server
• title : Title for the API Doc
• desc : Descri
• context : The context of the API Doc, an instance of Context class
• parsed_classes : A list containing all newly created classes, instances of HydraClass
• other_classes : List containg all default classes, such as Collection and Resource, also instances of HydraClass
• collections : List containing all collections to be added to the API, instance of HydraCollection
• status : List containing possible status of the API, instances of HydraStatus
• entrypoint : A new HydraEntryPoint object for the API Doc.

Each object has a generate() method that returns a Python dictionary generated according to Hydra specs

To add classes to the API Doc, we need to do the following

api_doc = HydraDoc("serverapi",
                   "API Doc for the server side API",
                   "API Documentation for the server side system",
                   "serverapi",
                   "http://hydrus.com/")

drone = HydraClass("Drone", "Drone", "Class for a drone", endpoint=True)
# Properties
drone.add_supported_prop(HydraClassProp("vocab:Status", "DroneStatus", True, False, False))
# Operations
drone.add_supported_op(HydraClassOp("ChangeStatus",
                                    "POST",
                                    "vocab:Status",
                                    None,
                                    [{"code": 200, "description": "Status Changed"}]))
drone.add_supported_op(HydraClassOp("GetStatus",
                                    "GET",
                                    None,
                                    "vocab:Status",
                                    [{"code": 200, "description": "Status Returned"}]))

api_doc.add_supported_class(drone, collection=True)

api_doc.add_baseResource()
api_doc.add_baseCollection()
api_doc.gen_EntryPoint()

We can add the default Collection and Resource classes to the API Doc by using

api_doc.add_baseResource()
api_doc.add_baseCollection()

Using the endpoint=True option when creating the HydraClass will automatically create endpoints in the EntryPoint object for the HydraClass and it's operations when gen_EntryPoint() is called.

Using the collection=True option when adding a class to the API Doc, a HydraCollection object is automatically generated for the same. An endpoint for every Collection is automatically generated when gen_EntryPoint() is called with the appropriate GET method. Collections can be added manually as well with predefined operations similar to HydraClass. These operations are automatically assigned endpoints when the gen_EntryPoint() is called.

Now that we have an abstract way of defining, generating and editing the API Documentation for an API, we must see how these classes can be combined with models so that both the data and the documentation are in the same object.

@xadahiya, @Mec-iS Please review this and let me know if everything that is needed is properly generated. We can incorporate this into Hydrus and replace all documentation and generated functions using a single HydraDoc instance. Parsed classes can be accessed from api_doc.parsed_classes although we can generate everythin directly using the "HydraDoc" object.

Please review it, once you are done with comments, I will add this to Hydrus and make changes to get everything running.

Also, I added new docs for drone and server. I don't know which one @xadahiya is using for the simulation, but please have a look at the docs I wrote and see if they can be used.

[xadahiya]

Moved to hydrus repo