Is it possible to generate only a single API endpoint?

[AmberWilkie]

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]

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']

• https://github.com/zipmark/rspec_api_documentation/blob/4cfef51eb0b6d5544ed35ec115e5073403ba2825/lib/tasks/docs.rake#L4-L5

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

• https://github.com/zipmark/rspec_api_documentation/blob/4cfef51eb0b6d5544ed35ec115e5073403ba2825/lib/tasks/docs.rake#L10-L11

[simeonwillbanks]

@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]

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

[adelnabiullin]

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:

1. spec/spec_helper.rb

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

2. 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

3. then run the command:

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

4. got an error mentioned below

[oestrich]

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]

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]

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

https://github.com/zipmark/rspec_api_documentation/pull/433

Thanks!

[knzai]

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]

@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.