haveapi 0.31.1 → 0.32.0

data/doc/documentation-ui.md

@@ -0,0 +1,192 @@
+# Browsing API documentation
+
+Open a version endpoint such as `/v7.0/` for the overview and client
+initialization examples. The overview lists the available client libraries and
+configured API clients. Choose **Authentication** for sign-in examples or
+**Resources** for the full resource directory. Nested resources have their own pages, with
+breadcrumbs linking to their parents. The sidebar identifies the current
+resource by its full dotted path, such as `vps.snapshot`, above its action links.
+
+The brand identifies the API, with its version on a separate line. The API root
+lists available versions. HaveAPI internals opens the framework README; its
+sidebar links to the protocol and client-development references.
+
+Resource URLs use `?resource=vps` or `?resource=vps.snapshot`; the directory uses
+`?page=resources` and authentication uses `?page=authentication`. These selectors
+apply only to HTML documentation, leaving API actions and OPTIONS descriptions
+unchanged. A version URL without the final slash redirects to its canonical
+slash URL and retains the query. Mounted APIs retain
+their prefix, for example `/api/v7.0/?resource=vps`. The unselected API root
+continues to list versions; a selector there uses the default version.
+Malformed or ambiguous selectors return 400. Resources absent from the current
+user's description return 404. Navigation, examples and legacy anchor mappings
+use the same filtered description. Ordinary documentation pages use
+`private, no-store`; compact search data has a separate private-cache policy
+described below.
+
+Each resource page shows that resource's own actions and links to its children.
+The sidebar lists its direct subresources. While scrolling, the current action
+expands to show its Input parameters, Output parameters and Examples links.
+Authentication methods provide links to their sections in the same way.
+Without JavaScript, all of these section links remain visible. Reference
+headings have permalink icons for linking to a particular section.
+Action links retain their existing `root-...` fragments. Old overview links
+with resource, action or example fragments open the corresponding resource page
+when JavaScript is enabled. Ordinary resource links work without JavaScript;
+the resource directory remains usable without JavaScript.
+
+## Search and visibility
+
+Search is available in the sidebar on every documentation page. Press `/` to
+focus it; on small screens this opens the navigation. The shortcut leaves normal
+typing in editable fields alone. Search finds resource names, action
+names, aliases and paths, and input or output parameter names, labels and types.
+Versioned pages search their selected API version. The versions index and
+HaveAPI internals search the default version, identified in the search label.
+Search does not include protocol text, examples, defaults or validator values.
+
+Results open the resource, action or parameter row. Queries use the normal
+resource-directory page, such as `?page=resources&q=hostname`, and work without
+JavaScript. With JavaScript enabled, using the search field loads a compact
+list of searchable metadata. Further typing searches that list locally.
+Resources appear before actions, followed by parameters. Resource results show
+the full path, including parent resources. The list shows at most
+20 matches and asks the reader to refine queries with more results. Submitting
+the form opens the results page.
+
+The first search may take time to load. The browser can reuse its private cached
+copy when navigating between freshly rendered pages with the same visible API
+metadata. Search follows the documentation snapshot shown on the page; an open
+page can retain that snapshot until reloaded. Opening a result checks access
+again. The versions index, internal pages and pages restored from browser history
+load a fresh snapshot when search is used. The search enhancement does not save
+queries or results in preferences or JavaScript storage.
+
+Anonymous documentation shows all declared resources, actions and parameters.
+Signed-in documentation and search results show only those accessible to the
+current account. Open **Documentation settings** beside the API name for theme
+choices and the available OAuth sign-in or account controls. Signed-in readers
+see their username and **Sign out**. Supported OAuth clients also offer
+**Switch user**, which ends the documentation session
+and starts a fresh sign-in. If that next sign-in is cancelled, the old session
+remains signed out. The note below the controls states which view is shown.
+Each API request still checks authorization
+for its particular operation; a documentation entry does not grant permission
+to execute it.
+
+Parameter Details contain a Validation rules table with one row per advertised
+rule. Allowed values appear in code beside their display labels. String choices
+have no added quotation marks; other values retain their types.
+Validation messages and extra options remain available; unknown rules retain
+their supplied details. The Required column, defaults and API validation
+behavior are unchanged. On narrow screens, parameter tables and long code blocks
+scroll within their own regions.
+
+Version-specific navigation puts Authentication before Resources and indents
+authentication methods beneath it. Technical references are linked under
+HaveAPI internals in the versions-index sidebar, and retain their direct URLs.
+
+## Themes and examples
+
+The sidebar controls theme, language, client variant and example detail for
+all examples on the page. Open **Documentation settings** and use the **Theme**
+controls to select **Automatic**, **Light** or **Dark**. Automatic follows the
+operating system. The versions index and shared internal pages use the same
+layout and theme choices.
+
+**Simple** examples focus on the operation and assume an initialized `api`
+client, authenticated when required. **With error handling** demonstrates
+additional error checks or diagnostics. Initialization and authentication
+examples remain on their respective pages.
+
+Choose a language first. The Client selector appears when that language has
+multiple variants, such as Callback and Async. Examples stays visible and shows
+the choices supported by the selected client on the current page. A selector
+with only one choice is disabled.
+
+A client can offer only Simple on an initialization page and both levels on an
+action page. Each example uses With error handling only when that group supports
+it; other groups remain Simple. A singleton choice preserves the saved detail
+preference for pages and clients that support both levels. Replace the literal
+credentials in authentication examples with the values for your application.
+
+Use the copy icon inside a code block's top-right corner to copy its displayed code.
+If the browser cannot copy it, select the code and copy it manually. Copying an
+example does not change the selected language, detail or scroll position.
+
+The browser stores these choices in `haveapi.docs.preferences.v1`. Preference
+data contains no credentials or API responses. Choices are checked against the
+clients available in the current API; an unavailable saved client uses an
+available fallback.
+Storage failures leave the controls usable for the current page. Without
+JavaScript, native disclosure panels keep the examples readable.
+
+## Extending documentation
+
+Client renderers declare `language`, `language_label` and optional `variant`
+metadata alongside their stable client `id`. Unspecified presentation metadata
+falls back to the renderer's ID and label. Only available renderers appear;
+Go, Rust and TypeScript API clients require their configured profiles. See
+[client examples](client-examples.md) for renderer and profile configuration.
+
+Set the server's optional `documentation_name` before mounting to use a specific
+API name or canonical domain in the brand and page titles. Without it, the
+reference displays the request host and any nondefault port. The name is display
+text; it does not change action URLs, OAuth endpoints or redirects.
+
+Renderers can declare `detail_levels :simple` or
+`detail_levels :simple, :thorough`. Declarations are inherited; undeclared custom
+renderers keep both levels for compatibility. Declare a single level when the
+renderer has no separate error-handling format. A renderer can refine its choices
+for each group with `detail_levels_for(kind, context:, result:,
+auth_method: nil, auth_description: nil)`, using the already-rendered Simple
+result. The base query preserves the inherited declaration, including for
+custom limitation results. Return only a frozen `[:simple]` or
+`[:simple, :thorough]`. This controls presentation and does not change direct
+renderer calls or Context detail values. See the
+[renderer extension contract](client-examples.md#renderer-extensions) for the
+built-in policies and adapter interface.
+
+HTML selection traverses description keys rather than Ruby constants or file
+paths. Keep UI navigation separate from any complete private schema used by a
+client generator for name resolution. New content should retain stable action
+and example IDs, escaped source and the shared current-user description.
+
+Search metadata comes from that request's authorized description. Versioned
+HTML derives one compact projection and a content key; it includes only the key
+and index URL in the page. The index contains names, labels, types, paths and
+parent references, with no examples, defaults, validator values or account
+identity. Ruby result pages and browser suggestions match the same projection.
+
+The keyed index representation uses `private, max-age=86400, immutable` and
+varies by credentials and the configured locale header. A network request still
+authenticates, describes the current view and checks the key before returning
+data or a conditional success. Changed views return 409 without index data.
+Bootstrap responses, errors and responses changing cookies remain no-store.
+There is no server snapshot cache, background permission polling or persistent
+JavaScript index. Logout does not erase private HTTP-cache files; a fresh page
+can reuse an entry only when its authorized metadata has the same content key.
+
+## Browser sign-in
+
+APIs can optionally configure an OAuth documentation client for browser sign-in.
+The server keeps its client secret and uses a secure encrypted cookie for the
+documentation session. This session applies only to HTML documentation; API
+actions still use their ordinary credentials. See the
+[OAuth setup guide](documentation-oauth.md) for configuration and HTTPS
+requirements. APIs without that configuration show anonymous documentation and
+no sign-in control. HTTP Basic, bearer headers and query credentials do not sign
+readers into the documentation. Their API authentication examples remain available.
+
+For a single-version API, the versions index uses that version's
+documentation authentication and shows its actual account controls. With
+multiple versions, the index hides account controls rather than assuming their
+authentication is compatible. Internal articles remain neutral and may link to
+the single version's authentication page without claiming a signed-in identity.
+
+Documentation identity comes only from its valid OAuth session cookie. Cached
+Basic credentials for another user do not change that identity or its controls;
+an absent or invalid cookie leaves the reader anonymous. Ordinary API actions
+and OPTIONS descriptions continue to use their existing authentication. See the
+OAuth setup guide for enabling account selection on a dedicated documentation
+client.

data/doc/index.md

@@ -1,7 +1,4 @@
-HaveAPI documentation
-=====================
+# HaveAPI internals
 
- - [README](doc/readme)
- - [Protocol definition](doc/protocol.md)
- - [JSON schema of the documentation protocol](doc/json-schema)
- - [How to create a client](doc/create-client.md)
+These pages describe the HaveAPI protocol and how to develop clients.
+Choose a reference from the sidebar.

data/doc/performance.md

@@ -44,16 +44,22 @@ outside measurement. Three batches of eight renders check allocations, and a
 separate Ruby-call count checks traversal growth; each allows 32 additional
 objects or calls per render. Output must remain identical and inputs unchanged.
 
-Complete Rack HTML requests enable all three generated profiles. Checks compare
-every registered initialization/authentication/action panel with real renderer
-output, including successful and failed samples, and exercise admin/member/admin
-isolation through the same adapters. Allocation measurements use pages with
-2, 4 and 8 resources, each with two actions and three admin-visible samples per
-action, plus one admin-only action. Member pages hide the admin sample and action.
-The added-resource allocation increment may grow by at most 2.5 times when the
-resource increment doubles. This permits linear panel/output growth while
-rejecting the measured whole-description-per-example copy regression. The
-fixture uses scalar fields so Go action panels exercise supported code paths.
+Rack HTML checks enable all three generated profiles and request the overview,
+authentication page, resource directory and every resource page. Each panel is
+compared with the real renderer output at both detail levels, including successful and failed
+samples. Admin/member/admin requests verify isolation through the same adapters;
+a selected resource page must not render another resource's action examples.
+The fixture uses scalar fields so Go action panels exercise supported code paths.
+
+Allocation measurements cover two dimensions at the unchanged 2.5 increment
+ratio. With 2, 4 and 8 resources, a fixed request set (overview, authentication,
+directory and resource0) measures growth from the authorized description and
+navigation.
+Separately, one selected resource with 2, 4 and 8 ordinary actions measures
+panel growth and detects repeated whole-resource or whole-description copies.
+Both dimensions retain the existing samples and admin-only action. Measured
+page bytes are recorded separately from complete-site correctness bytes; summing
+all resource pages would also count their repeated page structure.
 
 The log retains the named registry, kinds, allocations, Ruby-call counts and
 page byte counts. These deterministic checks measure the selected candidate.
@@ -151,8 +157,25 @@ Rust panels, authorization boundaries and operation counts. They use relative
 allocation and deterministic checks without inventing fixed-reference allocation
 ceilings for the new shapes. Existing calibrated workload budgets remain intact.
 
-These shapes exercise complete pages with several megabytes of HTML, so a
-single request provides substantial measurement work. The weekly shape doubles
+The HTML workloads retain one GET to the version overview for each operation,
+with unchanged fixture dimensions, counters and budgets. The validator accepts
+the legacy complete-page layout or the current overview as explicit, separate
+shapes. It checks the overview's resource-directory link, complete authorized
+resource/action anchor map and real initialization panels, and rejects action
+bodies or private sample values there. The current overview intentionally omits resource examples;
+its smaller response does not establish that resource-page rendering is faster.
+The separate all-client checks cover the directory inventory, resource pages and
+both detail levels.
+
+Documentation HTML on sources supporting the optional documentation OAuth client
+uses a real encrypted session cookie. Historical sources retain their Basic
+authentication setup; API, OPTIONS and direct renderer lanes keep their original
+credentials. Cookie issuance happens during fixture setup, with stable per-role
+CSRF. Every HTML request still decrypts the cookie and validates its token through
+the OAuth provider. Samples record the selected identity mode and role.
+
+Historical complete-page shapes can contain several megabytes of HTML, so a
+single request can provide substantial measurement work. The weekly shape doubles
 the resource count. Actual batch durations and output sizes belong in each
 run's evidence; these synthetic shapes do not define production latency targets.
 
@@ -243,6 +266,10 @@ fails during activation. Historical
 quick allocation calibration and all existing reference/budget bytes are retained
 unchanged, without claiming that the original quick calibration loaded Rust.
 
+The benchmark worker activates io-console 0.9.4 before loading source or fixture
+code, so its dependency graph does not depend on which examples a page renders.
+Missing or conflicting versions fail before requests begin.
+
 The root, Ruby server and Rust generator development Gemfiles declare JSON
 2.21.2 so fresh setup installs the recorded native dependency. Comparisons
 accept only that exact declaration change in these three files. They retain

data/haveapi.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = ">= #{File.read('../../.ruby-version').strip}"
 
   s.add_dependency 'activesupport', '>= 7.1'
-  s.add_dependency 'haveapi-client', '~> 0.31.1'
+  s.add_dependency 'haveapi-client', '~> 0.32.0'
   s.add_dependency 'i18n', '>= 1.6', '< 2'
   s.add_dependency 'json'
   s.add_dependency 'mail'

data/lib/haveapi/authentication/chain.rb

@@ -48,6 +48,20 @@ module HaveAPI::Authentication
       nil
     end
 
+    # Validate an explicit documentation cookie token without API credentials.
+    def authenticate_oauth2_token(version, request, token)
+      catch(:return) do
+        Array(@instances[version]).each do |provider|
+          next unless provider.name == :oauth2 && provider.respond_to?(:authenticate_access_token)
+
+          user = provider.authenticate_access_token(request, token)
+          return user if user
+        end
+      end
+
+      nil
+    end
+
     def describe(context)
       ret = {}
 
@@ -71,6 +85,11 @@ module HaveAPI::Authentication
       ret
     end
 
+    # Metadata only: no resource traversal or authentication is performed.
+    def provider_descriptions(version)
+      Array(@instances[version]).to_h { |provider| [provider.name, provider.describe] }
+    end
+
     # Return provider list for version `v`.
     # Used for registering providers to specific version, e.g.
     #   api.auth_chain[1] << MyAuthProvider

data/lib/haveapi/authentication/oauth2/provider.rb

@@ -130,7 +130,13 @@ module HaveAPI::Authentication
                   HaveAPI.t('haveapi.authentication.multiple_oauth2_tokens')
           end
 
-        token && config.find_user_by_access_token(request, token)
+        token && authenticate_access_token(request, token)
+      rescue HaveAPI::AuthenticationError
+        nil
+      end
+
+      def authenticate_access_token(request, token)
+        config.find_user_by_access_token(request, token)
       rescue HaveAPI::AuthenticationError
         nil
       end

data/lib/haveapi/client_example.rb

@@ -9,6 +9,9 @@ module HaveAPI
   # Methods `example`, `request` and `response` take one argument, the example
   # to describe.
   class ClientExample
+    SIMPLE_DETAIL_LEVELS = [:simple].freeze
+    DEFAULT_DETAIL_LEVELS = %i[simple thorough].freeze
+
     class << self
       # All subclasses have to call this method to set their label and be
       # registered.
@@ -46,6 +49,42 @@ module HaveAPI
         true
       end
 
+      def language(value = nil)
+        @language = value.to_s.freeze unless value.nil?
+        @language || id
+      end
+
+      def language_label(value = nil)
+        @language_label = value.to_s.freeze unless value.nil?
+        @language_label || label
+      end
+
+      def variant(value = nil)
+        @variant = value.to_s.freeze unless value.nil?
+        @variant
+      end
+
+      def detail_levels(*values)
+        @detail_levels = validated_detail_levels(values) unless values.empty?
+        return @detail_levels if instance_variable_defined?(:@detail_levels)
+
+        superclass.respond_to?(:detail_levels) ? superclass.detail_levels : DEFAULT_DETAIL_LEVELS
+      end
+
+      # Custom renderers retain their declaration, including for limitations.
+      # Built-ins refine this using the already-rendered Simple result.
+      def detail_levels_for(_kind, context:, result:, auth_method: nil, auth_description: nil)
+        detail_levels
+      end
+
+      # Older, explicitly pinned generator adapters only provide resolve/render.
+      # Their unknown detail semantics retain this wrapper's declaration.
+      def adapter_detail_levels_for(adapter:, kind:, context:, result:, mode:, auth_method: nil, auth_description: nil)
+        return detail_levels unless adapter.respond_to?(:detail_levels_for)
+
+        validated_detail_levels(adapter.detail_levels_for(kind:, context:, result:, mode:, auth_method:, auth_description:))
+      end
+
       def render(kind, context:, auth_method: nil, auth_description: nil)
         arguments = [context.host, context.base_url, context.version]
         arguments.push(context.resource_path, context.resource, context.action_name, context.action) if kind == :example
@@ -98,6 +137,16 @@ module HaveAPI
       def clients
         @clients.sort { |a, b| a.order <=> b.order }
       end
+
+      private
+
+      def validated_detail_levels(values)
+        unless [SIMPLE_DETAIL_LEVELS, DEFAULT_DETAIL_LEVELS].include?(values)
+          raise ArgumentError, 'Example detail levels must be :simple or :simple, :thorough'
+        end
+
+        values.frozen? ? values : values.dup.freeze
+      end
     end
 
     attr_reader :resource_path, :resource, :action_name, :action, :host, :base_url, :version, :context
@@ -118,31 +167,110 @@ module HaveAPI
       self
     end
 
+    def thorough?
+      context&.detail == :thorough
+    end
+
     def version_url
       File.join(base_url, "v#{version}", '/')
     end
 
     protected
 
-    # @param password [Boolean] include password parameter
-    # @return [Hash<String, String>] parameter => example value
-    def auth_token_credentials(desc, password: true)
-      passwords = %i[password pass passwd]
-      params = desc[:resources][:token][:actions]['request'][:input][:parameters].keys - %i[lifetime interval]
+    class UnsupportedAuthentication < StandardError; end
+
+    def auth_field(value, name, default = nil)
+      return default unless value.is_a?(Hash)
 
-      unless password
-        params.reject! { |param| passwords.include?(param) }
+      value.fetch(name) { value.fetch(name.to_s, default) }
+    end
+
+    def auth_token_actions(description)
+      token = auth_field(auth_field(description, :resources, {}), :token, {})
+      auth_field(token, :actions, {})
+    end
+
+    def auth_token_parameters(description, action = :request)
+      info = auth_field(auth_token_actions(description), action, {})
+      input = auth_field(info, :input, {})
+      unless [nil, :hash, 'hash', :object, 'object'].include?(auth_field(input, :layout))
+        raise UnsupportedAuthentication, 'This token example requires object input.'
+      end
+
+      auth_field(input, :parameters, {})
+    end
+
+    # Only advertised machine types/finite constraints supply public literals.
+    # Defaults, prose and current-user data are deliberately not consulted.
+    def auth_literal(name, parameter, excluding: [])
+      type = auth_field(parameter, :type)
+      value = case type
+              when 'String', 'Text' then %w[password pass passwd].include?(name.to_s) ? 'secret' : name.to_s
+              when 'Integer', 'Resource' then 1
+              when 'Float' then 1.0
+              when 'Boolean' then excluding.include?(false)
+              when 'Datetime' then '2026-01-01T00:00:00Z'
+              when 'Custom' then {}
+              else raise UnsupportedAuthentication, 'This token example has an unsupported input type.'
+              end
+      validators = auth_field(parameter, :validators, {})
+      inclusion = auth_field(auth_field(validators, :include, {}), :values)
+      values = inclusion.is_a?(Hash) ? inclusion.keys : inclusion
+      acceptance = auth_field(validators, :accept)
+      if acceptance.is_a?(Hash) && (acceptance.has_key?(:value) || acceptance.has_key?('value'))
+        value = auth_field(acceptance, :value)
+      elsif values.is_a?(Array)
+        raise UnsupportedAuthentication, 'This token example has no advertised input choice.' if values.empty?
+
+        value = values.find { |choice| !excluding.include?(choice) }
+      end
+      value = 'fixed' if name.to_s == 'lifetime'
+      value = value.to_s if value.is_a?(Symbol) && %w[String Text].include?(type)
+      if excluding.include?(value)
+        raise UnsupportedAuthentication, 'This token client cannot send the advertised login input value.'
+      end
+
+      compatible = case type
+                   when 'String', 'Text', 'Datetime' then value.is_a?(String)
+                   when 'Integer' then value.is_a?(Integer)
+                   when 'Resource' then value.is_a?(Integer) || value.is_a?(String)
+                   when 'Float' then value.is_a?(Numeric) && value.finite?
+                   when 'Boolean' then [true, false].include?(value)
+                   when 'Custom' then value.is_a?(Hash) || value.is_a?(Array) || value.is_a?(String) || value.is_a?(Numeric) || [true, false, nil].include?(value)
+                   end
+      compatible &&= values.map { |item| item.is_a?(Symbol) ? item.to_s : item }.include?(value) if values.is_a?(Array)
+      compatible &&= value == auth_field(acceptance, :value) if acceptance.is_a?(Hash)
+      raise UnsupportedAuthentication, 'This token example cannot represent its advertised input choice.' unless compatible
+
+      value
+    end
+
+    def auth_login_literal(_name, _parameter, value)
+      value
+    end
+
+    # @param password [Boolean] include an interactive password parameter
+    def auth_token_credentials(description, password: true, action: :request)
+      auth_token_parameters(description, action).each_with_object({}) do |(name, parameter), input|
+        next if name.to_s == 'token' || (!password && %w[password pass passwd].include?(name.to_s))
+        next if name.to_s == 'interval' && !auth_field(parameter, :required)
+
+        begin
+          value = auth_literal(name, parameter)
+        rescue UnsupportedAuthentication
+          raise if auth_field(parameter, :required) || name.to_s == 'lifetime'
+
+          next
+        end
+        input[name.to_s] = action.to_s == 'request' ? auth_login_literal(name, parameter, value) : value
       end
+    end
 
-      params.to_h do |param|
-        value =
-          if passwords.include?(param)
-            'secret'
-          else
-            param
-          end
+    def auth_token_continuations(description)
+      auth_token_actions(description).each_with_object({}) do |(name, _action), result|
+        next if %w[request renew revoke].include?(name.to_s)
 
-        [param, value]
+        result[name.to_s] = auth_token_credentials(description, action: name)
       end
     end
   end

data/lib/haveapi/client_examples/curl.rb

@@ -1,14 +1,16 @@
-require 'pp'
+require 'shellwords'
 require 'haveapi/client_examples/http'
 
 module HaveAPI::ClientExamples
   class Curl < Http
     label 'curl'
+    language 'curl'
+    language_label 'curl'
     code :bash
     order 90
 
     def init
-      "$ curl --request OPTIONS '#{version_url}'"
+      "$ curl --request OPTIONS #{Shellwords.escape(version_url)}"
     end
 
     def auth(method, desc)
@@ -17,35 +19,41 @@ module HaveAPI::ClientExamples
         <<~END
           # Password is asked on standard input
           $ curl --request OPTIONS \\
-                 --user username \\
-                 '#{base_url}'
-          Password: secret
+                 --user user \\
+                 #{Shellwords.escape(base_url)}
+          # Password: secret
 
           # Password given on the command line
           $ curl --request OPTIONS \\
-                 --user username:secret \\
-                 '#{base_url}'
+                 --user user:secret \\
+                 #{Shellwords.escape(base_url)}
         END
 
       when :token
-        login = auth_token_credentials(desc).merge(lifetime: 'fixed')
+        login = auth_token_credentials(desc)
 
         <<~END
           # Acquire the token
           $ curl --request POST \\
                  --header 'Content-Type: application/json' \\
-                 --data-binary "#{format_data(token: login)}" \\
-                 '#{File.join(base_url, '_auth', 'token', 'tokens')}'
+                 --data-binary #{Shellwords.escape(JSON.generate(token: login))} \\
+                 #{Shellwords.escape(File.join(base_url, '_auth', 'token', 'tokens'))}
 
           # Use a previously acquired token
           $ curl --request OPTIONS \\
-                 --header '#{desc[:http_header]}: thetoken' \\
-                 '#{base_url}'
+                 --header #{Shellwords.escape("#{desc[:http_header]}: example-token")} \\
+                 #{Shellwords.escape(base_url)}
         END
 
       when :oauth2
         '# See RFC 6749 for authorization process and RFC 6750 for access token usage.'
       end
+    rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
+      { status: :limitation, reason: e.message }.freeze
+    end
+
+    def example(sample)
+      "#{request(sample)}\n#{comment_response(response(sample))}"
     end
 
     def request(sample)
@@ -64,9 +72,9 @@ module HaveAPI::ClientExamples
       })
 
       <<~END
-        $ curl --request #{action[:method]} \\
-               --data-binary "#{data}" \\
-               '#{url}'
+        $ curl --request #{Shellwords.escape(action[:method].to_s)} \\
+               --data-binary #{data} \\
+               #{Shellwords.escape(url)}
       END
     end
 
@@ -80,11 +88,13 @@ module HaveAPI::ClientExamples
     end
 
     def format_data(data)
-      json = JSON.pretty_generate(data)
-      json.split("\n").map do |line|
-        out = ''
-        PP.pp(line, out).strip[1..-2]
-      end.join("\n")
+      Shellwords.escape(JSON.generate(data))
+    end
+
+    private
+
+    def comment_response(fragment)
+      fragment.gsub(/\r\n?/, "\n").lines.map { |line| "# #{line.delete_suffix("\n")}\n" }.join
     end
   end
 end

data/lib/haveapi/client_examples/dynamic_helpers.rb

@@ -13,7 +13,7 @@ module HaveAPI::ClientExamples
 
     def code_result
       { status: :code, code: yield.freeze }.freeze
-    rescue Unsupported, JSON::GeneratorError => e
+    rescue Unsupported, HaveAPI::ClientExample::UnsupportedAuthentication, JSON::GeneratorError => e
       { status: :limitation, reason: e.message.freeze }.freeze
     end