GET requests without any body do not get rendered #55

elvanja · 2019-12-06T15:33:39Z

While documenting a GET request endpoint, e.g. /resources/:uuid?signature= with 1 path param (the :uuid and one query param (the :signature), I found that the request from related test isn't rendered in docs at all.

I thought I found the problem in lib/blue_bird/writer/blueprint.ex:141:

    req_str =
      [
        request.headers |> filter_headers() |> print_headers() |> indent(4),
        request.body_params |> print_attributes |> indent(4),
        request.body_params |> print_body_params |> indent(4)
      ]
      |> Enum.reject(&(&1 == ""))
      |> Enum.join("\n")

It creates attributes (print_attributes) from body params, which are already covered by &print_body_params/1. So, I made it work with:

    req_str =
      [
        request.headers |> filter_headers() |> print_headers() |> indent(4),
        Map.merge(request.path_params, request.query_params) |> print_attributes |> indent(4),
        request.body_params |> print_body_params |> indent(4)
      ]
      |> Enum.reject(&(&1 == ""))
      |> Enum.join("\n")

That produces the related Attributes section in apib file:

+ Request Test title

    + Attributes (object)

            + uuid (string)
            + signature (string)

Unfortunately, rendering that as HTML doesn't output anything so only request title is actually rendered:

So couple of things would make sense to me here:

to include attribute value from the test
attributes to be actually rendered with request

Not sure where the problem with rendering lies, hence no PR. If you can point me in the right direction, I'd be happy to contribute.

The text was updated successfully, but these errors were encountered:

woylie · 2019-12-06T16:19:54Z

I haven't worked with API Blueprint in a while, but if I remember correctly, attributes are only used to describe attributes found in the body (https://apiblueprint.org/documentation/examples/08-attributes.html). If you want to document path parameters, you have to add an attributes block (https://apiblueprint.org/documentation/specification.html#def-uriparameters-section).

The route parameters are written here: https://github.com/KittyHeaven/blue_bird/blob/master/lib/blue_bird/writer/blueprint.ex#L83

The generator module is responsible for turning the test data and api docs into the struct that is going to be written: https://github.com/KittyHeaven/blue_bird/blob/master/lib/blue_bird/generator.ex#L1

Were you able to reproduce the problem in a test?

elvanja · 2019-12-09T07:15:34Z

The route parameters render just fine. What I wanted to do is to show the test executed GET url in request/response section. Maybe best described via example.

Given test:

    test "redirects resource request", %{conn: conn} do
      conn =
        conn
        |> get(
          Routes.resources_execute_path(
            conn,
            :execute,
            "e868e42e-5714-4745-8d9a-607b8a346579",
            %{"signature" => "82a21e67090a4e23984cf87d376719a5aa424a5fe093426194bc17ffd28c21e2"}
          )
        )
        |> ConnLogger.save(title: "Redirect resource")

      assert redirected_to(conn) =~ "http://dummy.url"
    end

It generates the following api.apib file:

FORMAT: 1A
HOST: https://host.com/

# SAMPLE API


# Group Example

## /resources/{uuid}{?signature}

### Execute [GET]
Sample request for https://github.com/KittyHeaven/blue_bird/issues/55.


+ Parameters

    + uuid (string, required) - UUID of the resource.


    + signature (string, required) - A SHA256 signature used to authenticate the request.


+ Response 302 (text/html; charset=utf-8)

    + Headers

            cache-control: max-age=0, private, must-revalidate
            cross-origin-window-policy: deny
            location: http://dummy.url

    + Body

            <html><body>You are being <a href="http://dummy.url">redirected</a>.</body></html>

Which results in:

So what's missing for me is the request from test. We have the response (with 302 status) with all the details (headers, body) and is fine, but we're missing the actual request. It would ideally be some section that:

has the title of the request Redirect resource, as defined by test
shows the GET test url being actually invoked, e.g. https://host.com/resources/e868e42e-5714-4745-8d9a-607b8a346579?signature=82a21e67090a4e23984cf87d376719a5aa424a5fe093426194bc17ffd28c21e2, executed in test

I mean, we get all that with POST, where related payload is shown along with title. For GET requests it makes sense (at least to me) to show similar data. It would certainly help with multiple request/response test cases, where we'd have pairs of those in docs. Currently, only responses are shown and it's not always clear what the request was for particular response.

Not even sure that this is doable via ApiBlueprint, hence the question 😄
Hope I'm making sense here.

woylie · 2019-12-22T17:23:37Z

If I understand the specification correctly, the request section inherits from the payload section, which can have headers, attributes, body and schema sections as children. It seems that all these child sections relate to the request body, so if you specify attributes here, this is interpreted to be a description of the JSON request body and rendered accordingly.

I don't see a way to show the request uri including the query parameters or to describe the actual query parameters in the request. The uri parameters of a request are inherited from the parent section, cannot be overwritten and will only be rendered globally, not per request. The best thing we could do is to extract the query parameter values and add them to the global parameter section as example values (https://apiblueprint.org/documentation/specification.html#def-uriparameters-section), but we can only have one example value per parameter.

elvanja · 2019-12-23T13:23:48Z

I actually found several issues that are related to this (at least it seems like that to me!):

Last one is a merged PR even. But, if I read all that correctly, it looks like something is planned to support showing actual parameters with GET requests, but it's not there yet. So, it looks like there's nothing to be done for the moment. Thanks for your time!

woylie closed this as completed Dec 24, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GET requests without any body do not get rendered #55

GET requests without any body do not get rendered #55

elvanja commented Dec 6, 2019

woylie commented Dec 6, 2019

elvanja commented Dec 9, 2019

woylie commented Dec 22, 2019

elvanja commented Dec 23, 2019 •

edited

Loading

GET requests without any body do not get rendered #55

GET requests without any body do not get rendered #55

Comments

elvanja commented Dec 6, 2019

woylie commented Dec 6, 2019

elvanja commented Dec 9, 2019

woylie commented Dec 22, 2019

elvanja commented Dec 23, 2019 • edited Loading

elvanja commented Dec 23, 2019 •

edited

Loading