Mercurial > hg > orthanc

comparison OrthancFramework/Sources/RestApi/RestApiCallDocumentation.cpp @ 4401:354ea95b294a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documenting system calls
author Sebastien Jodogne <s.jodogne@gmail.com>
date Wed, 23 Dec 2020 15:13:45 +0100
parents 029366f95217
children ad646ff506d0
comparison
equal deleted inserted replaced
4400:029366f95217 4401:354ea95b294a
102 102
103 return *this; 103 return *this;
104 } 104 }
105 105
106 106
107 RestApiCallDocumentation& RestApiCallDocumentation::SetUriComponent(const std::string& name, 107 RestApiCallDocumentation& RestApiCallDocumentation::SetUriArgument(const std::string& name,
108 Type type, 108 Type type,
109 const std::string& description) 109 const std::string& description)
110 { 110 {
111 if (uriComponents_.find(name) != uriComponents_.end()) 111 if (uriArguments_.find(name) != uriArguments_.end())
112 { 112 {
113 throw OrthancException(ErrorCode_ParameterOutOfRange, "URI component \"" + name + "\" is already documented"); 113 throw OrthancException(ErrorCode_ParameterOutOfRange, "URI argument \"" + name + "\" is already documented");
114 } 114 }
115 else 115 else
116 { 116 {
117 Parameter p; 117 Parameter p;
118 p.type_ = type; 118 p.type_ = type;
119 p.description_ = description; 119 p.description_ = description;
120 uriComponents_[name] = p; 120 uriArguments_[name] = p;
121 return *this; 121 return *this;
122 } 122 }
123 } 123 }
124 124
125 125
187 return *this; 187 return *this;
188 } 188 }
189 } 189 }
190 190
191 191
192 void RestApiCallDocumentation::SetHttpGetSample(const std::string& url) 192 void RestApiCallDocumentation::SetHttpGetSample(const std::string& url,
193 bool isJson)
193 { 194 {
194 #if ORTHANC_ENABLE_CURL == 1 195 #if ORTHANC_ENABLE_CURL == 1
195 HttpClient client; 196 HttpClient client;
196 client.SetUrl(url); 197 client.SetUrl(url);
197 client.SetHttpsVerifyPeers(false); 198 client.SetHttpsVerifyPeers(false);
198 if (!client.Apply(sample_)) 199
199 { 200 if (isJson)
200 LOG(ERROR) << "Cannot GET: " << url; 201 {
201 sample_ = Json::nullValue; 202 if (!client.Apply(sampleJson_))
203 {
204 LOG(ERROR) << "Cannot GET: " << url;
205 sampleJson_ = Json::nullValue;
206 }
207 }
208 else
209 {
210 if (client.Apply(sampleText_))
211 {
212 hasSampleText_ = true;
213 }
214 else
215 {
216 LOG(ERROR) << "Cannot GET: " << url;
217 hasSampleText_ = false;
218 }
202 } 219 }
203 #else 220 #else
204 LOG(WARNING) << "HTTP client is not available to generated the documentation"; 221 LOG(WARNING) << "HTTP client is not available to generated the documentation";
205 #endif 222 #endif
206 } 223 }
231 throw OrthancException(ErrorCode_ParameterOutOfRange); 248 throw OrthancException(ErrorCode_ParameterOutOfRange);
232 } 249 }
233 } 250 }
234 251
235 252
236 bool RestApiCallDocumentation::FormatOpenApi(Json::Value& target) const 253 bool RestApiCallDocumentation::FormatOpenApi(Json::Value& target,
254 const std::set<std::string>& expectedUriArguments) const
237 { 255 {
238 if (summary_.empty() && 256 if (summary_.empty() &&
239 description_.empty()) 257 description_.empty())
240 { 258 {
241 return false; 259 return false;
308 p["description"] = field->second.description_; 326 p["description"] = field->second.description_;
309 schema["properties"][field->first] = p; 327 schema["properties"][field->first] = p;
310 } 328 }
311 } 329 }
312 } 330 }
313 331
314 if (sample_.type() != Json::nullValue) 332 if (sampleJson_.type() != Json::nullValue)
315 { 333 {
316 target["responses"]["200"]["content"]["application/json"]["schema"]["example"] = sample_; 334 target["responses"]["200"]["content"][EnumerationToString(MimeType_Json)]["schema"]["example"] = sampleJson_;
317 } 335 }
318 else 336 else if (answerTypes_.find(MimeType_Json) != answerTypes_.end())
319 { 337 {
320 target["responses"]["200"]["content"]["application/json"]["examples"] = Json::arrayValue; 338 target["responses"]["200"]["content"][EnumerationToString(MimeType_Json)]["examples"] = Json::objectValue;
339 }
340
341 if (hasSampleText_)
342 {
343 target["responses"]["200"]["content"][EnumerationToString(MimeType_PlainText)]["example"] = sampleText_;
321 } 344 }
322 345
323 Json::Value parameters = Json::arrayValue; 346 Json::Value parameters = Json::arrayValue;
324 347
325 for (Parameters::const_iterator it = getArguments_.begin(); 348 for (Parameters::const_iterator it = getArguments_.begin();
342 p["schema"]["type"] = TypeToString(it->second.type_); 365 p["schema"]["type"] = TypeToString(it->second.type_);
343 p["description"] = it->second.description_; 366 p["description"] = it->second.description_;
344 parameters.append(p); 367 parameters.append(p);
345 } 368 }
346 369
347 for (Parameters::const_iterator it = uriComponents_.begin(); 370 for (Parameters::const_iterator it = uriArguments_.begin();
348 it != uriComponents_.end(); ++it) 371 it != uriArguments_.end(); ++it)
349 { 372 {
373 if (expectedUriArguments.find(it->first) == expectedUriArguments.end())
374 {
375 throw OrthancException(ErrorCode_InternalError, "Unexpected URI argument: " + it->first);
376 }
377
350 Json::Value p = Json::objectValue; 378 Json::Value p = Json::objectValue;
351 p["name"] = it->first; 379 p["name"] = it->first;
352 p["in"] = "path"; 380 p["in"] = "path";
353 p["required"] = true; 381 p["required"] = true;
354 p["schema"]["type"] = TypeToString(it->second.type_); 382 p["schema"]["type"] = TypeToString(it->second.type_);
355 p["description"] = it->second.description_; 383 p["description"] = it->second.description_;
356 parameters.append(p); 384 parameters.append(p);
357 } 385 }
358 386
387 for (std::set<std::string>::const_iterator it = expectedUriArguments.begin();
388 it != expectedUriArguments.end(); ++it)
389 {
390 if (uriArguments_.find(*it) == uriArguments_.end())
391 {
392 LOG(WARNING) << "Adding missing expected URI argument: " << *it;
393 Json::Value p = Json::objectValue;
394 p["name"] = *it;
395 p["in"] = "path";
396 p["required"] = true;
397 p["schema"]["type"] = "string";
398 p["description"] = "";
399 parameters.append(p);
400 }
401 }
402
359 target["parameters"] = parameters; 403 target["parameters"] = parameters;
360 404
361 return true; 405 return true;
362 } 406 }
363 } 407 }