haveapi 0.31.1 → 0.32.0

data/spec/documentation/fixtures/search_index.json

@@ -0,0 +1,476 @@
+{
+  "index": {
+    "format": 1,
+    "version": "1",
+    "base_path": "/api/v1/",
+    "locale": "cs",
+    "visibility": "anonymous",
+    "resources": [
+      {
+        "path": [
+          "bulk"
+        ],
+        "label": "Bulk",
+        "authentication": null,
+        "search": [
+          "bulk",
+          "Bulk",
+          "bulk",
+          "Bulk"
+        ]
+      },
+      {
+        "path": [
+          "mywidget"
+        ],
+        "label": "Mywidget",
+        "authentication": null,
+        "search": [
+          "mywidget",
+          "Mywidget",
+          "mywidget",
+          "Mywidget"
+        ]
+      },
+      {
+        "path": [
+          "síť"
+        ],
+        "label": "Síť",
+        "authentication": null,
+        "search": [
+          "síť",
+          "Síť",
+          "síť",
+          "Síť"
+        ]
+      },
+      {
+        "path": [
+          "síť",
+          "žluťoučký"
+        ],
+        "label": "Žluťoučký",
+        "authentication": null,
+        "search": [
+          "síť",
+          "Síť",
+          "žluťoučký",
+          "Žluťoučký",
+          "síť.žluťoučký",
+          "Žluťoučký"
+        ]
+      },
+      {
+        "path": [
+          "widget"
+        ],
+        "label": "Widget",
+        "authentication": null,
+        "search": [
+          "widget",
+          "Widget",
+          "widget",
+          "Widget"
+        ]
+      },
+      {
+        "path": [
+          "token"
+        ],
+        "label": "Token",
+        "authentication": "token",
+        "search": [
+          "token",
+          "Token",
+          "token",
+          "Token",
+          "token"
+        ]
+      }
+    ],
+    "actions": [
+      {
+        "resource": 0,
+        "name": "inspect",
+        "label": "Inspect",
+        "identifiers": [
+          "inspect",
+          "bulk.inspect"
+        ],
+        "search": [
+          "Inspect"
+        ]
+      },
+      {
+        "resource": 1,
+        "name": "widget",
+        "label": "Widget",
+        "identifiers": [
+          "widget",
+          "mywidget.widget"
+        ],
+        "search": [
+          "Widget"
+        ]
+      },
+      {
+        "resource": 1,
+        "name": "widget_long",
+        "label": "Widget long",
+        "identifiers": [
+          "widget_long",
+          "mywidget.widget_long"
+        ],
+        "search": [
+          "Widget long"
+        ]
+      },
+      {
+        "resource": 3,
+        "name": "obnovit",
+        "label": "Obnovit",
+        "identifiers": [
+          "obnovit",
+          "síť.žluťoučký.obnovit"
+        ],
+        "search": [
+          "Obnovit"
+        ]
+      },
+      {
+        "resource": 5,
+        "name": "request",
+        "label": "Request",
+        "identifiers": [
+          "request",
+          "token.request"
+        ],
+        "search": [
+          "Request"
+        ]
+      }
+    ],
+    "parameters": [
+      {
+        "action": 0,
+        "name": "bulkvalue00",
+        "label": "Bulkvalue00",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue00"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue01",
+        "label": "Bulkvalue01",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue01"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue02",
+        "label": "Bulkvalue02",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue02"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue03",
+        "label": "Bulkvalue03",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue03"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue04",
+        "label": "Bulkvalue04",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue04"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue05",
+        "label": "Bulkvalue05",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue05"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue06",
+        "label": "Bulkvalue06",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue06"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue07",
+        "label": "Bulkvalue07",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue07"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue08",
+        "label": "Bulkvalue08",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue08"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue09",
+        "label": "Bulkvalue09",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue09"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue10",
+        "label": "Bulkvalue10",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue10"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue11",
+        "label": "Bulkvalue11",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue11"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue12",
+        "label": "Bulkvalue12",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue12"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue13",
+        "label": "Bulkvalue13",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue13"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue14",
+        "label": "Bulkvalue14",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue14"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue15",
+        "label": "Bulkvalue15",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue15"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue16",
+        "label": "Bulkvalue16",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue16"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue17",
+        "label": "Bulkvalue17",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue17"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue18",
+        "label": "Bulkvalue18",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue18"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue19",
+        "label": "Bulkvalue19",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue19"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue20",
+        "label": "Bulkvalue20",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue20"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue21",
+        "label": "Bulkvalue21",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue21"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue22",
+        "label": "Bulkvalue22",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue22"
+      },
+      {
+        "action": 0,
+        "name": "bulkvalue23",
+        "label": "Bulkvalue23",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Bulkvalue23"
+      },
+      {
+        "action": 1,
+        "name": "widget",
+        "label": "Widget",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Widget"
+      },
+      {
+        "action": 2,
+        "name": "widget_long",
+        "label": "Widget long",
+        "type": "String",
+        "direction": "input",
+        "humanized_name": "Widget long"
+      },
+      {
+        "action": 3,
+        "name": "číslo",
+        "label": "Číslo",
+        "type": "Integer",
+        "direction": "input",
+        "humanized_name": "Číslo"
+      },
+      {
+        "action": 3,
+        "name": "výsledek",
+        "label": "Výsledek",
+        "type": "String",
+        "direction": "output",
+        "humanized_name": "Výsledek"
+      },
+      {
+        "action": 4,
+        "name": "lifetime",
+        "label": "Lifetime",
+        "type": "Integer",
+        "direction": "input",
+        "humanized_name": "Lifetime"
+      },
+      {
+        "action": 4,
+        "name": "lifetime",
+        "label": "Lifetime",
+        "type": "Integer",
+        "direction": "output",
+        "humanized_name": "Lifetime"
+      }
+    ]
+  },
+  "queries": [
+    {
+      "query": "widget",
+      "expected": [
+        "resource::widget:::widget",
+        "resource::mywidget:::mywidget",
+        "action::mywidget:widget::widget",
+        "action::mywidget:widget_long::widget_long",
+        "parameter::mywidget:widget:input:widget",
+        "parameter::mywidget:widget_long:input:widget_long"
+      ],
+      "more": false
+    },
+    {
+      "query": "SÍŤ ČÍSLO",
+      "expected": [
+        "parameter::síť.žluťoučký:obnovit:input:číslo"
+      ],
+      "more": false
+    },
+    {
+      "query": "token lifetime",
+      "expected": [
+        "parameter:token:token:request:input:lifetime",
+        "parameter:token:token:request:output:lifetime"
+      ],
+      "more": false
+    },
+    {
+      "query": "bulkvalue",
+      "expected": [
+        "parameter::bulk:inspect:input:bulkvalue00",
+        "parameter::bulk:inspect:input:bulkvalue01",
+        "parameter::bulk:inspect:input:bulkvalue02",
+        "parameter::bulk:inspect:input:bulkvalue03",
+        "parameter::bulk:inspect:input:bulkvalue04",
+        "parameter::bulk:inspect:input:bulkvalue05",
+        "parameter::bulk:inspect:input:bulkvalue06",
+        "parameter::bulk:inspect:input:bulkvalue07",
+        "parameter::bulk:inspect:input:bulkvalue08",
+        "parameter::bulk:inspect:input:bulkvalue09",
+        "parameter::bulk:inspect:input:bulkvalue10",
+        "parameter::bulk:inspect:input:bulkvalue11",
+        "parameter::bulk:inspect:input:bulkvalue12",
+        "parameter::bulk:inspect:input:bulkvalue13",
+        "parameter::bulk:inspect:input:bulkvalue14",
+        "parameter::bulk:inspect:input:bulkvalue15",
+        "parameter::bulk:inspect:input:bulkvalue16",
+        "parameter::bulk:inspect:input:bulkvalue17",
+        "parameter::bulk:inspect:input:bulkvalue18",
+        "parameter::bulk:inspect:input:bulkvalue19"
+      ],
+      "more": true
+    },
+    {
+      "query": "absent",
+      "expected": [],
+      "more": false
+    }
+  ],
+  "display_queries": [
+    {
+      "query": "síť",
+      "expected": [
+        { "title": "Resource: síť", "context": ["Síť"] },
+        { "title": "Resource: síť.žluťoučký", "context": ["Síť · Žluťoučký"] },
+        { "title": "Action: obnovit", "context": ["síť.žluťoučký · obnovit", "Obnovit"] },
+        { "title": "Parameter: výsledek", "context": ["síť.žluťoučký · obnovit", "Output · String", "Výsledek"] },
+        { "title": "Parameter: číslo", "context": ["síť.žluťoučký · obnovit", "Input · Integer", "Číslo"] }
+      ]
+    },
+    {
+      "query": "token lifetime",
+      "expected": [
+        { "title": "Parameter: lifetime", "context": ["token · request", "Input · Integer", "Authentication: token", "Lifetime"] },
+        { "title": "Parameter: lifetime", "context": ["token · request", "Output · Integer", "Authentication: token", "Lifetime"] }
+      ]
+    }
+  ]
+}

data/spec/documentation/identity_and_guides_spec.rb

@@ -0,0 +1,130 @@
+require 'spec_helper'
+
+module DocumentationIdentitySpec
+  User = Struct.new(:login)
+
+  class Provider < HaveAPI::Authentication::Basic::Provider
+    protected
+
+    def find_user(_request, username, password)
+      User.new(username) if password == 'pass'
+    end
+  end
+end
+
+describe DocumentationIdentitySpec do
+  api do
+    define_resource(:Sample) do
+      version 1
+      auth false
+      define_action(:Index, superclass: HaveAPI::Actions::Default::Index) do
+        input(:hash) { string :admin_field, choices: { values: { 'secret-value' => 'Admin choice' } } }
+        authorize do |user|
+          input blacklist: [:admin_field] if user && user.login != 'admin'
+          allow
+        end
+      end
+    end
+  end
+  default_version 1
+  auth_chain DocumentationIdentitySpec::Provider
+
+  it 'shows anonymous visibility and themes without Basic controls when docs OAuth is absent' do
+    login('admin', 'pass')
+    get '/v1/'
+    expect(last_response).to be_ok
+    expect(last_response.body).to include('Showing all resources, actions and parameters.', 'Using this reference',
+                                          'data-documentation-menu', 'aria-label="Documentation settings"',
+                                          '<span id="docs-theme-label" class="docs-theme-label">Theme</span>')
+    choices = last_response.body.match(%r{<div class="docs-theme-choices" role="group" aria-labelledby="docs-theme-label">(.*?)</div>}m)[1]
+    expect(choices).to include('data-theme-choice="auto"', 'data-theme-choice="light"', 'data-theme-choice="dark"')
+    expect(last_response.body.scan('id="docs-theme-label"').length).to eq(1)
+    expect(last_response.body).not_to include('docs-identity', 'docs-sign-in', 'data-account-menu', 'data-theme-menu')
+    expect(last_response.body.index('docs-visibility-note')).to be < last_response.body.index('data-documentation-search')
+  end
+
+  it 'uses the requested primary order and indents methods beneath Authentication' do
+    get '/v1/?page=authentication'
+    primary = last_response.body.match(%r{<nav aria-label="Documentation pages">(.*?)</nav>\s*</li>\s*<li>}m)
+    expect(primary).not_to be_nil
+    body = primary[1]
+    expect(body.index('Overview')).to be < body.index('Authentication')
+    expect(body).to include('docs-authentication-submenu', 'href="#auth-basic"')
+    sidebar = last_response.body.match(%r{<aside[^>]*>(.*?)</aside>}m)[1]
+    expect(sidebar.index('Authentication')).to be < sidebar.index('>Resources</a>')
+    expect(sidebar).not_to include('Guides', 'doc/protocol', 'doc/client-examples')
+  end
+
+  it 'keeps technical links explicitly in internals and removes the index content link' do
+    get '/'
+    main = last_response.body.match(%r{<main[^>]*>(.*?)</main>}m)[1]
+    expect(main).not_to include('>Documentation</a>')
+    expect(last_response.body).to include('HaveAPI internals', 'doc/client-examples')
+    get '/v1/'
+    expect(last_response.body).not_to include('HaveAPI internals', 'doc/client-examples')
+  end
+
+  it 'renders real fenced examples on technical pages and README as code' do
+    get '/doc/client-examples'
+    expect(last_response).to be_ok
+    expect(last_response.body).to match(/<pre><code[^>]*>.*?documentation_clients/m)
+    expect(last_response.body).not_to include('```ruby')
+    get '/doc/readme'
+    expect(last_response).to be_ok
+    expect(last_response.body).not_to include('```')
+  end
+
+  context 'with an actual documentation OAuth cookie' do
+    let(:documentation_server) { HaveAPI::Server.new(self.class::ApiModule) }
+    let(:users) do
+      { 1 => { 'member-token' => DocumentationIdentitySpec::User.new('<member>&'),
+               'admin-token' => DocumentationIdentitySpec::User.new('admin') } }
+    end
+    let(:fixture) do
+      require_relative '../../test_support/documentation_oauth_fixture'
+      server = documentation_server
+      server.use_version(1)
+      oauth = DocumentationOAuthFixture.configure(server, users:)
+      server.mount('/')
+      @api = server
+      oauth
+    end
+
+    before { fixture }
+
+    def cookie_request(token, path = '/v1/?resource=sample')
+      oauth = fixture
+      get "#{oauth.origin}#{path}", {}, 'HTTP_COOKIE' => oauth.header_for(documentation_server, version: 1, token:)
+    end
+
+    it 'shows visible Sign in and neutral Account labels beside their person icons' do
+      get "#{fixture.origin}/v1/"
+      expect(last_response.body).to match(%r{class="docs-sign-in"[^>]*>\s*<svg.*?</svg>\s*<span>Sign in</span>}m)
+      get "#{fixture.origin}/doc"
+      expect(last_response.body).to match(%r{class="docs-account-link"[^>]*><svg.*?</svg><span>Account</span>}m)
+      expect(fixture.lookups).to be_empty
+    end
+
+    it 'shows the actual escaped login once in the shared settings menu with CSRF sign-out' do
+      cookie_request('member-token')
+      expect(last_response).to be_ok
+      menu = last_response.body.match(%r{<details data-documentation-menu>(.*?)</details>}m)[1]
+      expect(menu).to include('data-documentation-menu-content', '<span class="docs-identity">&lt;member&gt;&amp;</span>',
+                              '<form method="post"', 'name="csrf"', '<button type="submit">Sign out</button>')
+      expect(menu).not_to include('docs-visibility-note', 'data-account-menu', 'data-theme-menu', 'name="switch_user"')
+      expect(last_response.body.scan('class="docs-identity"').length).to eq(1)
+      expect(last_response.body).to include('Showing resources, actions and parameters available to this account.')
+      expect(fixture.lookups).to eq([[1, 'member-token']])
+    end
+
+    it 'uses cookie roles for parameter choices despite conflicting Basic credentials' do
+      login('admin', 'pass')
+      cookie_request('member-token')
+      expect(last_response.body).not_to include('admin_field', 'secret-value', 'Admin choice')
+      login('member', 'pass')
+      cookie_request('admin-token')
+      expect(last_response.body).to include('admin_field', 'secret-value', 'Admin choice')
+      expect(fixture.lookups).to eq([[1, 'member-token'], [1, 'admin-token']])
+    end
+  end
+end