api-hogs / bureaucrat

Generate Phoenix API documentation from tests
https://hexdocs.pm/bureaucrat/api-reference.html
The Unlicense
368 stars 73 forks source link

Parameters in doc() causing list conversion Error #23

Closed utf4 closed 6 years ago

utf4 commented 7 years ago

I am facing the following error when passing :operation_id in doc().

[error] GenEvent handler Bureaucrat.Formatter installed in #PID<0.359.0> terminating ** (ArgumentError) cannot convert the given list to a string.

To be converted to a string, a list must contain only:

  • strings
  • integers representing Unicode codepoints
  • or a list containing one of these three elements

Please check the given list or call inspect/1 to get the list representation, got:

[operation_id: "create_user"]

(elixir) lib/list.ex:709: List.to_string/1
(bureaucrat) lib/bureaucrat/markdown_writer.ex:43: Bureaucrat.MarkdownWriter.write_example/2
(elixir) lib/enum.ex:645: Enum."-each/2-lists^foreach/1-0-"/2
(elixir) lib/enum.ex:645: Enum.each/2
(elixir) lib/enum.ex:651: anonymous fn/3 in Enum.each/2
(stdlib) lists.erl:1263: :lists.foldl/3
(elixir) lib/enum.ex:1772: Enum.each/2
(elixir) lib/enum.ex:645: Enum."-each/2-lists^foreach/1-0-"/2
(elixir) lib/enum.ex:645: Enum.each/2
(elixir) lib/enum.ex:1233: anonymous fn/3 in Enum.map/2
(stdlib) lists.erl:1263: :lists.foldl/3
(elixir) lib/enum.ex:1772: Enum.map/2
(bureaucrat) lib/bureaucrat/formatter.ex:10: Bureaucrat.Formatter.handle_event/2
(stdlib) gen_event.erl:570: :gen_event.server_update/4
(stdlib) gen_event.erl:552: :gen_event.server_notify/4
(stdlib) gen_event.erl:293: :gen_event.handle_msg/5
(stdlib) proc_lib.erl:247: :proc_lib.init_p_do_apply/3

Last message: {:suite_finished, 985361, nil} State: nil

My Environment: $ mix -v Erlang/OTP 20 [erts-9.0] [source] [64-bit] [smp:1:1] [ds:1:1:10] [async-threads:10] [hipe] [kernel-poll:false] Mix 1.4.4

mbuhot commented 7 years ago

I can see from the stacktrace that the default MarkdownWriter is being used, but it might be an older version, because the function Bureaucrat.MarkdownWriter.write_example/2 isn't on line 43 in the current master, it's now starting on line 54

If you would like Bureaucrat to use :operation_id to merge test examples with a swagger file, you need to switch to the SwaggerSlateMarkdownWriter.

Eg:

Bureaucrat.start(
  env_var: "DOC",
  writer: Bureaucrat.SwaggerSlateMarkdownWriter,
  default_path: "doc/source/index.html.md",
  swagger: "priv/static/swagger.json" |> File.read!() |> Poison.decode!())