How to document query?

[Vi-vi-Vi]

Hello,

Thanks for this very good project!

My API uses a query which is defined as follow:

  ENDPOINT_INFO(getComputedValues) {
    // general
    info->summary = "Compute values corresponding to the input parameters";
    info->addResponse<ComputedValuesDto::ObjectWrapper>(Status::CODE_200, "application/json");
    info->addResponse<String>(Status::CODE_404, "text/plain");
    // params specific
    info->queryParams["param1"].description = "Input value 1";

  }
  ENDPOINT("GET", "compute/*", getComputedValues,
           REQUEST(std::shared_ptr<IncomingRequest>, request) // Map request object to endpoint method
          ) {
     //...
     
  }

I would like to generate the documentation using swagger but for the query, I only get the following view:

How to make the query parameter appears in Swagger UI and /api-docs/oas-3.0.0.json like described in OpenApi Doc #query-parameters

Thanks,

[lganzzzo]

Hello @Vi-vi-Vi ,

Thank you for the question and your interest in the project!

Please see the examples:

Add query parameter manually

  ENDPOINT_INFO(getComputedValues) {
    // general
    info->summary = "Compute values corresponding to the input parameters";
    info->addResponse<UserDto::ObjectWrapper>(Status::CODE_200, "application/json");
    info->addResponse<String>(Status::CODE_404, "text/plain");
    // params specific
    info->queryParams.add<String>("param1").description = "Input value 1"; // add query parameter manually
    info->queryParams.add<String>("param2").description = "Input value 2"; // add query parameter manually
    info->queryParams.add<String>("param3"); // add query parameter with no description manually
    info->queryParams["param3"].required = false; // make parameter optional
  }
  ENDPOINT("GET", "compute/*", getComputedValues,
           REQUEST(std::shared_ptr<IncomingRequest>, request) // Map request object to endpoint method
  ) {

    auto p1 = request->getQueryParameter("param1", "" /* default value */);
    auto p2 = request->getQueryParameter("param2", "" /* default value */);
    auto p3 = request->getQueryParameter("param3", "" /* default value */);

    OATPP_LOGD("Endpoint", "p1=%s, p2=%s, p3=%s", p1->getData(), p2->getData(), p3->getData());

    return createResponse(Status::CODE_200, "ok");

  }

Add query parameters by mapping param to a method variable

ENDPOINT_INFO(getComputedValues2) {
    // general
    info->summary = "Compute values corresponding to the input parameters";
    info->addResponse<UserDto::ObjectWrapper>(Status::CODE_200, "application/json");
    info->addResponse<String>(Status::CODE_404, "text/plain");
    // params specific
    info->queryParams["param1"].description = "Input value 1";
    info->queryParams["param2"].description = "Input value 2";
    info->queryParams["my-param-name"].description = "Input value 3";
  }
  ENDPOINT("GET", "compute2/*", getComputedValues2,
           QUERY(String, param1), // Add query parameters by mapping param to a method variable
           QUERY(String, param2),
           QUERY(String, param3, "my-param-name") // query param with name qualifier
  ) {

    OATPP_LOGD("Endpoint", "p1=%s, p2=%s, p3=%s", param1->getData(), param2->getData(), param3->getData());

    return createResponse(Status::CODE_200, "ok");
  }

Please let me know if you have more questions.

Best Regards,
Leonid

[Vi-vi-Vi]

Thanks very much. It works perfectly!

[acidtonic]

Is this possible for repeating query params?

Such as ?status=1&status=2&status=3

Since the number of repeating params can be variable, can swagger handle this?

[lganzzzo]

Hey @acidtonic ,

Not yet. At the moment you can't parse query params as an array of values.