Mercurial > hg > orthanc
comparison OrthancFramework/Sources/RestApi/RestApiCallDocumentation.cpp @ 4401:354ea95b294a
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 } |