Is it possible to generate only a single API endpoint? #355

AmberWilkie · 2017-08-17T12:04:55Z

Every time we change one route, we have to update all of the docs. It would be lovely to be able to update only one file (or based on one acceptance test file, etc.). My apologies in advance if the answer is obvious and I failed at finding it.

simeonwillbanks · 2018-01-18T16:22:31Z

I'm experiencing the same issue.

How about a Pull Request which introduces a pattern option to the rake tasks?

rake docs:generate['spec/acceptance/user_spec.rb']
rake docs:generate['spec/acceptance/v1/*_spec.rb']

rspec_api_documentation/lib/tasks/docs.rake

Lines 4 to 5 in 4cfef51

RSpec::Core::RakeTask.new('docs:generate') do |t|

t.pattern = 'spec/acceptance/**/*_spec.rb'

rake docs:generate:ordered['spec/acceptance/user_spec.rb']
rake docs:generate:ordered['spec/acceptance/v1/*_spec.rb']

rspec_api_documentation/lib/tasks/docs.rake

Lines 10 to 11 in 4cfef51

RSpec::Core::RakeTask.new('docs:generate:ordered') do |t|

t.pattern = 'spec/acceptance/**/*_spec.rb'

simeonwillbanks · 2018-01-18T17:12:39Z

@iamvery suggested an environment variable instead of an argument since rake task arguments can be tricky across different shells. e.g. bash and zsh

rake docs:generate SPEC_PATH_PATTERN=spec/acceptance/user_spec.rb

iamvery · 2018-01-18T17:19:40Z

(the idea comes from other uses I've seen, e.g. bin/rails db:migrate:down VERSION=xxxx; also HI 👋 )

adelnabiullin · 2018-10-23T15:01:12Z

At this moment there is a possibility to use this to generate single endpoint: https://github.com/zipmark/rspec_api_documentation#append_json

But unfortunately it does not work. I did everything like documented there, but got following error:

/Users/username/src/projectname/.bundle/ruby/2.5.0/gems/rspec_api_documentation-6.1.0/lib/rspec_api_documentation/writers/append_json_writer.rb:31:in 'block in as_json': undefined method 'section_hash' for #<RspecApiDocumentation::Writers::AppendJsonIndex:0x00007fa8aa999f30> (NoMethodError)

Steps to reproduce:

spec/spec_helper.rb

ENV["DOC_FORMAT"] ||= "json"
RspecApiDocumentation.configure do |config|
  config.format = ENV["DOC_FORMAT"]
end

lib/tasks/docs.rake

desc 'Generate API request documentation from API specs (by appending to existing)'
RSpec::Core::RakeTask.new('docs:generate:append', :spec_file) do |t, task_args|
  if spec_file = task_args[:spec_file]
    ENV["DOC_FORMAT"] = "append_json"
  end
  t.pattern    = spec_file || 'spec/acceptance/**/*_spec.rb'
  t.rspec_opts = ["--format RspecApiDocumentation::ApiFormatter"]
end

then run the command:

rake docs:generate:append\[spec/acceptance/orders_spec.rb\]

got an error mentioned below

oestrich · 2018-10-23T15:46:23Z

Looks like the append json format broke sometime recently. If you're interested in fixing it that'd be a great PR! I don't use append_json, so I don't know when I'll get a chance to look at this otherwise.

li-thy-um · 2019-02-22T06:18:20Z

here is my solution to generate Markdown file with SPEC_PATH_PATTERN

---
 lib/tasks/docs.rake                     | 11 +++++++++++
 spec/support/rspec_api_documentation.rb | 30 ++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/lib/tasks/docs.rake b/lib/tasks/docs.rake
new file mode 100644
index 00000000..fec2e566
--- /dev/null
+++ b/lib/tasks/docs.rake
@@ -0,0 +1,11 @@
+require 'rspec/core/rake_task'
+
+desc 'Generate API request documentation from API specs'
+RSpec::Core::RakeTask.new('docs:generate:append') do |t|
+  if ENV['SPEC_PATH_PATTERN']
+    t.pattern = ENV['SPEC_PATH_PATTERN']
+  else
+    t.pattern = 'spec/acceptance/**/*_spec.rb'
+  end
+  t.rspec_opts = ["--format RspecApiDocumentation::ApiFormatter"]
+end
diff --git a/spec/support/rspec_api_documentation.rb b/spec/support/rspec_api_documentation.rb
new file mode 100644
index 00000000..af62a9a6
--- /dev/null
+++ b/spec/support/rspec_api_documentation.rb
@@ -0,0 +1,30 @@
+module RspecApiDocumentation
+  module Writers
+    class MarkdownWriter
+      INDEX_FILE_NAME = 'index'
+
+      def self.clear_docs(docs_dir)
+        nil #noop
+      end
+
+      # Write out the generated documentation
+      def write
+        if render_options.fetch(:index, true) && !ENV['SPEC_PATH_PATTERN']
+          File.open(configuration.docs_dir.join(index_file_name + '.' + extension), "w+") do |f|
+            f.write markup_index_class.new(index, configuration).render
+          end
+        end
+
+        if render_options.fetch(:examples, true) && ENV['SPEC_PATH_PATTERN']
+          index.examples.each do |example|
+            markup_example = markup_example_class.new(example, configuration)
+            FileUtils.mkdir_p(configuration.docs_dir.join(markup_example.dirname))
+            File.open(configuration.docs_dir.join(markup_example.dirname, markup_example.filename), "w+") do |f|
+              f.write markup_example.render
+            end
+          end
+        end
+      end
+    end
+  end
+end

then run

alias gendoc='RAILS_ENV=test bundle exec rails docs:generate:append'
gendoc SPEC_PATH_PATTERN='./spec/acceptance/chars_spec.rb' && gendoc

it would print

Generating API Docs
Run options: include {:focus=>true}

All examples were filtered out; ignoring {:focus=>true}
  Chars
  GET /chars
    * 简繁体对照表
  PUT /chars
    * 整体更新简繁体对照表

Top 2 slowest examples (0.9137 seconds, 84.0% of total time):
  Chars GET /chars 简繁体对照表
    0.83632 seconds ./spec/acceptance/chars_spec.rb:18
  Chars PUT /chars 整体更新简繁体对照表
    0.07738 seconds ./spec/acceptance/chars_spec.rb:37

Finished in 1.09 seconds (files took 4.77 seconds to load)
2 examples, 0 failures

..............

and file changes

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   "doc/api/chars/\346\225\264\344\275\223\346\233\264\346\226\260\347\256\200\347\271\201\344\275\223\345\257\271\347\205\247\350\241\250.markdown"
	modified:   "doc/api/chars/\347\256\200\347\271\201\344\275\223\345\257\271\347\205\247\350\241\250.markdown"
	modified:   doc/api/index.markdown

mzemel · 2019-02-28T15:28:12Z

👋 Submitted this PR. Could anyone having problems try it and see if append_json now works?

#433

Thanks!

knzai · 2019-11-22T01:14:03Z

It's a loading/inheritance issue. If you change

AppendJsonIndex < JsonIndex

to

AppendJsonIndex < JSONIndex

it works. Maybe ruby version differences in some super logic.

knzai · 2019-11-22T01:17:01Z

@oestrich any chance either of making that tiny change, or that a PR would get accepted for it? Maintaining a fork or a monkey patch for three letters case change is a bit bonkers.

Closes zipmark#355

mzemel mentioned this issue Feb 28, 2019

Fixes missing JsonIndex#section_hash exception when using :append_json #433

Closed

EugZol added a commit to EugZol/rspec_api_documentation that referenced this issue Apr 8, 2020

Update append_json_writer.rb

102aebf

Closes zipmark#355

EugZol linked a pull request Apr 8, 2020 that will close this issue

Update append_json_writer.rb #472

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Is it possible to generate only a single API endpoint? #355

Is it possible to generate only a single API endpoint? #355

AmberWilkie commented Aug 17, 2017

simeonwillbanks commented Jan 18, 2018

simeonwillbanks commented Jan 18, 2018

iamvery commented Jan 18, 2018

adelnabiullin commented Oct 23, 2018 •

edited

Loading

oestrich commented Oct 23, 2018

li-thy-um commented Feb 22, 2019 •

edited

Loading

mzemel commented Feb 28, 2019

knzai commented Nov 22, 2019

knzai commented Nov 22, 2019 •

edited

Loading

Is it possible to generate only a single API endpoint? #355

Is it possible to generate only a single API endpoint? #355

Comments

AmberWilkie commented Aug 17, 2017

simeonwillbanks commented Jan 18, 2018

simeonwillbanks commented Jan 18, 2018

iamvery commented Jan 18, 2018

adelnabiullin commented Oct 23, 2018 • edited Loading

oestrich commented Oct 23, 2018

li-thy-um commented Feb 22, 2019 • edited Loading

mzemel commented Feb 28, 2019

knzai commented Nov 22, 2019

knzai commented Nov 22, 2019 • edited Loading

adelnabiullin commented Oct 23, 2018 •

edited

Loading

li-thy-um commented Feb 22, 2019 •

edited

Loading

knzai commented Nov 22, 2019 •

edited

Loading