From 1d232d6967f69c4867f41cf4d7258e2b8803068a Mon Sep 17 00:00:00 2001 From: Thomas Richter Date: Tue, 30 Apr 2013 11:40:19 +0200 Subject: [PATCH] some fixes in generateSwagger --- Documentation/Scripts/generateSwagger.py | 60 ++++++++-------- arangod/RestHandler/RestDocumentHandler.cpp | 76 +++++++++++++++------ 2 files changed, 88 insertions(+), 48 deletions(-) diff --git a/Documentation/Scripts/generateSwagger.py b/Documentation/Scripts/generateSwagger.py index 690aade3dc..04be8c4792 100644 --- a/Documentation/Scripts/generateSwagger.py +++ b/Documentation/Scripts/generateSwagger.py @@ -135,7 +135,7 @@ class StateMachine: class Regexen: def __init__(self): self.brief = re.compile('.*@brief') - self.RESTHEADER = re.compile('.*@RESTHEADER') + self.RESTHEADER = re.compile('.*@RESTHEADER{') self.RESTURLPARAMETERS = re.compile('.*@RESTURLPARAMETERS') self.RESTQUERYPARAMETERS = re.compile('.*@RESTQUERYPARAMETERS') self.RESTHEADERPARAMETERS = re.compile('.*@RESTHEADERPARAMETERS') @@ -161,8 +161,11 @@ def resturlparameters(cargo, r=Regexen()): if not line: return eof, (fp, line) elif r.read_through.match(line): return read_through, (fp, line) elif r.RESTURLPARAM.match(line): return resturlparam, (fp, line) + elif r.RESTQUERYPARAMETERS.match(line): return restqueryparameters, (fp, line) + elif r.RESTHEADERPARAMETERS.match(line): return restheaderparameters, (fp, line) + elif r.RESTBODYPARAM.match(line): return restbodyparam, (fp, line) elif r.RESTDESCRIPTION.match(line): return restdescription, (fp, line) - else: continue + else: continue def resturlparam(cargo, r=Regexen()): fp, last = cargo @@ -192,9 +195,12 @@ def restqueryparameters(cargo, r=Regexen()): line = fp.readline() if not line: return eof, (fp, line) elif r.read_through.match(line): return read_through, (fp, line) - elif r.RESTQUERYPARAM.match(line): return restqueryparam, (fp, line) + elif r.RESTURLPARAMETERS.match(line): return resturlparameters, (fp, line) + elif r.RESTHEADERPARAMETERS.match(line): return restheaderparameters, (fp, line) + elif r.RESTBODYPARAM.match(line): return restbodyparam, (fp, line) elif r.RESTDESCRIPTION.match(line): return restdescription, (fp, line) - else: continue + elif r.RESTQUERYPARAM.match(line): return restqueryparam, (fp, line) + else: continue def restheaderparameters(cargo, r=Regexen()): fp, last = cargo @@ -203,8 +209,11 @@ def restheaderparameters(cargo, r=Regexen()): if not line: return eof, (fp, line) elif r.read_through.match(line): return read_through, (fp, line) elif r.RESTHEADERPARAM.match(line): return restheaderparam, (fp, line) + elif r.RESTQUERYPARAMETERS.match(line): return restqueryparameters, (fp, line) + elif r.RESTURLPARAMETERS.match(line): return resturlparameters, (fp, line) + elif r.RESTBODYPARAM.match(line): return restbodyparam, (fp, line) elif r.RESTDESCRIPTION.match(line): return restdescription, (fp, line) - else: continue + else: continue def restheaderparam(cargo, r=Regexen()): # TODO @@ -213,35 +222,41 @@ def restheaderparam(cargo, r=Regexen()): para = {} para['paramType'] = 'header' para['dataType'] = parametersList[1].capitalize() - if parametersList[2] == 'required': - para['required'] = 'true' - else: - para['required'] = 'false' para['name'] = parametersList[0] para['description']='' while 1: line = fp.readline() if not line: return eof, (fp, line) elif r.read_through.match(line): return read_through, (fp, line) - elif r.RESTQUERYPARAMETERS.match(line): return restqueryparameters, (fp, line) - elif r.RESTBODYPARAM.match(line): return restbodyparam, (fp, line) - elif r.RESTDESCRIPTION.match(line): return restdescription, (fp, line) elif r.EMPTY_COMMENT.match(line): operation['parameters'].append(para) - return restqueryparameters, (fp, line) + return restheaderparameters, (fp, line) else: para['description'] += Typography(line[4:-1]) + ' ' def restbodyparam(cargo, r=Regexen()): - # TODO see POST processing in comment till PUT fp, last = cargo + parametersList = parameters(last).split(',') + para = {} + para['paramType'] = 'body' + para['dataType'] = parametersList[1].capitalize() + if parametersList[2] == 'required': + para['required'] = 'true' + para['name'] = parametersList[0] + para['description']='' while 1: line = fp.readline() if not line: return eof, (fp, line) elif r.read_through.match(line): return read_through, (fp, line) - elif r.RESTQUERYPARAM.match(line): return restqueryparam, (fp, line) + elif r.RESTURLPARAMETERS.match(line): return resturlparameters, (fp, line) + elif r.RESTHEADERPARAMETERS.match(line): return restheaderparameters, (fp, line) + elif r.RESTQUERYPARAMETERS.match(line): return restqueryparameters, (fp, line) elif r.RESTDESCRIPTION.match(line): return restdescription, (fp, line) - else: continue + elif r.EMPTY_COMMENT.match(line): + operation['parameters'].append(para) + return comment, (fp, line) + else: + para['description'] += Typography(line[4:-1]) + ' ' def restqueryparam(cargo, r=Regexen()): fp, last = cargo @@ -250,9 +265,7 @@ def restqueryparam(cargo, r=Regexen()): para['paramType'] = 'query' para['dataType'] = parametersList[1].capitalize() if parametersList[2] == 'required': - para['required'] = 'true' - else: - para['required'] = 'false' + para['required'] = 'True' para['name'] = parametersList[0] para['description']='' while 1: @@ -373,14 +386,6 @@ def comment(cargo, r=Regexen()): _operation = { 'httpMethod': None, 'nickname': None, 'parameters': [], 'summary': None, 'notes': '', 'examples': '', 'errorResponses':[]} _operation['httpMethod'] = method - if method == 'POST' or method == 'PUT' or method == 'PATCH': - parameter = {} - parameter['paramType'] = 'body' - parameter['name'] = 'body' - parameter['description'] = 'A valid json document for your data, for instance {"hello": "world"}.' - parameter['dataType'] = 'String' - parameter['required'] = 'false' - _operation['parameters'] = [parameter] summaryList = summary.split() _operation['nickname'] = summaryList[0] + ''.join([word.capitalize() for word in summaryList[1:]]) _operation['summary'] = summary @@ -389,6 +394,7 @@ def comment(cargo, r=Regexen()): operation = _operation elif r.RESTURLPARAMETERS.match(line): return resturlparameters, (fp, line) elif r.RESTHEADERPARAMETERS.match(line): return restheaderparameters, (fp, line) + elif r.RESTBODYPARAM.match(line): return restbodyparam, (fp, line) elif r.RESTQUERYPARAMETERS.match(line): return restqueryparameters, (fp, line) elif r.RESTDESCRIPTION.match(line): return restdescription, (fp, line) elif len(line) >= 4 and line[:4] == "////": continue diff --git a/arangod/RestHandler/RestDocumentHandler.cpp b/arangod/RestHandler/RestDocumentHandler.cpp index 139ab4f698..5748f76094 100644 --- a/arangod/RestHandler/RestDocumentHandler.cpp +++ b/arangod/RestHandler/RestDocumentHandler.cpp @@ -171,6 +171,9 @@ HttpHandler::status_e RestDocumentHandler::execute () { /// /// @RESTHEADER{POST /_api/document,creates a document} /// +/// @RESTBODYPARAM{document,json,required} +/// A JSON representation of document. +/// /// @RESTQUERYPARAMETERS /// /// @RESTQUERYPARAM{collection,string,required} @@ -462,6 +465,7 @@ bool RestDocumentHandler::readDocument () { /// @RESTURLPARAMETERS /// /// @RESTURLPARAM{document-handle,string,required} +/// The Handle of the Document. /// /// @RESTHEADERPARAMETERS /// @@ -639,11 +643,20 @@ bool RestDocumentHandler::readSingleDocument (bool generateBody) { /// @RESTQUERYPARAMETERS /// /// @RESTQUERYPARAM{collection,string,required} +/// The Id of the collection. /// /// @RESTDESCRIPTION /// Returns a list of all URI for all documents from the collection identified /// by `collection`. /// +/// @RESTRETURNCODES +/// +/// @RESTRETURNCODE{200} +/// All went good. +/// +/// @RESTRETURNCODE{404} +/// The collection does not exist. +/// /// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestReadDocumentAll} @@ -734,7 +747,25 @@ bool RestDocumentHandler::readAllDocuments () { /// @RESTURLPARAMETERS /// /// @RESTURLPARAM{document-handle,string,required} +/// The Handle of the Document. /// +/// @RESTQUERYPARAMETERS +/// +/// @RESTQUERYPARAM{rev,string,optional} +/// You can conditionally delete a document based on a target revision id by +/// using the `rev` URL parameter. +/// +/// @RESTQUERYPARAM{policy,string,optional} +/// To control the update behavior in case there is a revision mismatch, you +/// can use the `policy` parameter. This is the same as when replacing +/// documents (see replacing documents for more details). +/// +/// @RESTHEADERPARAMETERS +/// +/// @RESTHEADERPARAM{If-Match,string,optional} +/// You can conditionally delete a document based on a target revision id by +/// using the `if-match` HTTP header. +/// /// @RESTDESCRIPTION /// Like `GET`, but only returns the header fields and not the body. You /// can use this call to get the current revision of a document or check if @@ -795,6 +826,7 @@ bool RestDocumentHandler::checkDocument () { /// @RESTURLPARAMETERS /// /// @RESTURLPARAM{document-handle,string,required} +/// The Handle of the Document. /// /// @RESTQUERYPARAMETERS /// @@ -802,6 +834,9 @@ bool RestDocumentHandler::checkDocument () { /// /// @RESTQUERYPARAM{policy,string,optional} /// +/// @RESTQUERYPARAM{waitForSync,boolean,optional} +/// Wait until document has been sync to disk. +/// /// @RESTHEADERPARAMETERS /// /// @RESTHEADERPARAM{If-Match,string,optional} @@ -851,7 +886,8 @@ bool RestDocumentHandler::checkDocument () { /// /// For example, to conditionally replace a document based on a specific revision /// id, you the following request: -/// @REST{PUT /_api/document/`document-handle`?rev=`etag`} +/// +/// - PUT /_api/document/`document-handle`?rev=`etag` /// /// If a target revision id is provided in the request (e.g. via the `etag` value /// in the `rev` URL query parameter above), ArangoDB will check that @@ -862,7 +898,7 @@ bool RestDocumentHandler::checkDocument () { /// /// The conditional update behavior can be overriden with the `policy` URL query parameter: /// -/// @REST{PUT /_api/document/`document-handle`?policy=`policy`} +/// - PUT /_api/document/`document-handle`?policy=`policy` /// /// If `policy` is set to `error`, then the behavior is as before: replacements /// will fail if the revision id found in the database does not match the target @@ -993,6 +1029,7 @@ bool RestDocumentHandler::replaceDocument () { /// @RESTURLPARAMETERS /// /// @RESTURLPARAM{document-handle,string,required} +/// The Handle of the Document. /// /// @RESTQUERYPARAMETERS /// @@ -1002,6 +1039,9 @@ bool RestDocumentHandler::replaceDocument () { /// /// @RESTQUERYPARAM{policy,string,optional} /// +/// @RESTQUERYPARAM{waitForSync,boolean,optional} +/// Wait until document has been sync to disk. +/// /// @RESTHEADERPARAMETERS /// /// @RESTHEADERPARAM{If-Match,string,optional} @@ -1224,41 +1264,35 @@ bool RestDocumentHandler::modifyDocument (bool isPatch) { /// @RESTURLPARAMETERS /// /// @RESTURLPARAM{document-handle,string,required} +/// Deletes the document identified by `document-handle`. /// /// @RESTQUERYPARAMETERS /// /// @RESTQUERYPARAM{rev,string,optional} +/// You can conditionally delete a document based on a target revision id by +/// using the `rev` URL parameter. /// /// @RESTQUERYPARAM{policy,string,optional} -/// +/// To control the update behavior in case there is a revision mismatch, you +/// can use the `policy` parameter. This is the same as when replacing +/// documents (see replacing documents for more details). +/// +/// @RESTQUERYPARAM{waitForSync,boolean,optional} +/// Wait until document has been sync to disk. +/// /// @RESTHEADERPARAMETERS /// /// @RESTHEADERPARAM{If-Match,string,optional} +/// You can conditionally delete a document based on a target revision id by +/// using the `if-match` HTTP header. /// /// @RESTDESCRIPTION -/// Deletes the document identified by `document-handle`. If the document -/// exists and could be deleted, then a `HTTP 200` is returned. -/// /// The body of the response contains a JSON object with the information about /// the handle and the revision. The attribute `_id` contains the known /// `document-handle` of the updated document, the attribute `_rev` /// contains the known document revision. /// -/// If the document does not exist, then a `HTTP 404` is returned and the -/// body of the response contains an error document. -/// -/// You can conditionally delete a document based on a target revision id by -/// using either the `rev` URL parameter or the `if-match` HTTP header. -/// To control the update behavior in case there is a revision mismatch, you -/// can use the `policy` parameter. This is the same as when replacing -/// documents (see replacing documents for more details). -/// -/// Optionally, the URL parameter `waitForSync` can be used to force -/// synchronisation of the document deletion operation to disk even in case -/// that the `waitForSync` flag had been disabled for the entire collection. -/// Thus, the `waitForSync` URL parameter can be used to force synchronisation -/// of just specific operations. To use this, set the `waitForSync` parameter -/// to `true`. If the `waitForSync` parameter is not specified or set to +/// If the `waitForSync` parameter is not specified or set to /// `false`, then the collection's default `waitForSync` behavior is /// applied. The `waitForSync` URL parameter cannot be used to disable /// synchronisation for collections that have a default `waitForSync` value