Is there any way to include an image in documentation?

[dcvezzani]

I'm sure it's something simple that I'm missing, but no google or apipie repo searches are producing anything obvious.

E.g.,

In my controller...

  resource_description do
    short 'A top bar is a menu of links located at the top of the window'
    description <<-EOS
    Top bars are located at the top of the window and include an arrangement of links with a max of one nested level

    <img src="Pasted_Image_1_24_17__5_23_AM.png" alt="">
    EOS
  end

[dcvezzani]

According to the contents of the gemspec, RedCloth is being used for translating the markdown.

So this works; this is slightly different from the github markdown that I'm used to.

    [http://localhost:3000/images/Pasted_Image_1_24_17__5_23_AM.png]

Is there anyway to create a relative path to the image? Perhaps the question is which markdown is being used?

Hmm.

According to RedCloth, links should be generated as such:

"This is a link (This is a title)":http://www.textism.com

However, that doesn't work and I stumbled upon this which does work, but I have to put the dashes in to extend the term used for the hyperlink label.

obtained-a-valid-and-active-token[https://blah.com/core/wiki/Test-Api-Service-Calls-Locally]

RedCloth images should be using

!http://www.textism.com/common/textist.gif(Textist)!

but that's not working either.

I'm instead hosting the image elsewhere and using this to display the image in my documentation.

[https://blah.com/assets/23232/22250362/7a51f5b4-e1fb-11e6-8422-1e54693aa351.png]

[iNecas]

Hi, you should be able to used different markup handler if you like https://github.com/Apipie/apipie-rails#markup, if you find it better. Afaik RedCloth is used for Textile https://github.com/Apipie/apipie-rails/blob/master/lib/apipie/markup.rb#L42

[rshelfor]

I was hunting for a way to do this, trying to figure out how to correctlylink to the pre-compiled assets in production.

I tried using

description <<~DESC 
  rdoc-image:#{ActionController::Base.helpers.asset_path('/api/diagram.svg')}
DESC

But this wasn't working in production as it was just returning the same path I had passed in without looking up the pre-compiled digest image path.

To get around this, I created a diagrams controller that I could send a path to, and have it do the asset lookup, and redirect the request to the correct file.

# config/routes.rb
# ...
match 'diagrams/*image_path', to: 'diagrams#show', via: :get

# app/controllers/diagrams_controller.rb

  # GET diagrams/:image_path
  # Redirects to the image path
  def show
    redirect_to ActionController::Base.helpers.asset_path("#{params[:image_path]}.svg")
  end

Then I updated the link to :

description <<~DESC 
    rdoc-image:/diagrams/api/products/sequence
DESC

Then when I view the documentation, the request to /diagrams/api/products/sequence get sent to the diagrams controller, and redirected to the correctly digested .svg file.

If the provided path is wrong, the asset_path method will raise an error stating the asset is not present in the asset pipeline.

It would be nice if there was a simpler way to link to images in the the description for a method, or resource.