fix(docs/openapi): quickstart README and deterministic openapi generation

Author: gildesmarais

README.md

@@ -47,16 +47,23 @@ This trial run is intentionally minimal. Use Docker Compose for Browserless, aut
 
 ## Deploy (Docker Compose)
 
-1. Generate a key: `openssl rand -hex 32`.
-2. Export `HTML2RSS_SECRET_KEY`, `HEALTH_CHECK_TOKEN`, and `BROWSERLESS_IO_API_TOKEN` in your shell or `.env`.
-3. Export build metadata required by `docker-compose.yml`:
-   ```bash
-   export BUILD_TAG=local
-   export GIT_SHA="$(git rev-parse --short HEAD 2>/dev/null || echo dev)"
-   ```
-4. Optionally export `SENTRY_DSN` to send application errors to Sentry.
-5. Optionally export `SENTRY_ENABLE_LOGS=true` to forward structured application logs to Sentry.
-6. Start: `docker-compose up`.
+Quick start:
+
+```bash
+export HTML2RSS_SECRET_KEY="$(openssl rand -hex 32)"
+export HEALTH_CHECK_TOKEN="replace-with-a-strong-token"
+export BROWSERLESS_IO_API_TOKEN="replace-with-your-browserless-token"
+export BUILD_TAG="local"
+export GIT_SHA="$(git rev-parse --short HEAD 2>/dev/null || echo dev)"
+docker-compose up
+```
+
+Optional:
+
+```bash
+export SENTRY_DSN="https://examplePublicKey@o0.ingest.sentry.io/0"
+export SENTRY_ENABLE_LOGS=true
+```
 
 UI + API run on `http://localhost:4000`. The app exits if the secret key is missing.
 

public/openapi.yaml

@@ -277,8 +277,7 @@ paths:
                 <rss version="2.0"><channel><title>Error</title><description>Internal Server Error</description></channel></rss>
               schema:
                 type: string
-          description: returns non-cacheable json feed errors when service generation
-            fails
+          description: returns non-cacheable feed errors when service generation fails
       security: []
       summary: Render feed by token
       tags:
@@ -331,7 +330,7 @@ paths:
                 - success
                 - data
                 type: object
-          description: returns current health status when a valid bearer token is provided
+          description: returns health status when token is valid
         '401':
           content:
             application/json:

spec/html2rss/web/api/v1_spec.rb

@@ -214,7 +214,7 @@ def expected_featured_feeds
       expect(json.dig('data', 'health', 'status')).to eq('healthy')
     end
 
-    it 'returns health status when the configured environment token is valid', :aggregate_failures do
+    it 'returns health status when the configured environment token is valid', :aggregate_failures, openapi: false do
       ClimateControl.modify(HEALTH_CHECK_TOKEN: 'rotated-health-token') do
         allow(Html2rss::Web::Auth).to receive(:authenticate).and_call_original
 
@@ -227,7 +227,7 @@ def expected_featured_feeds
       end
     end
 
-    it 'returns health status after production-style env scrubbing', :aggregate_failures do
+    it 'returns health status after production-style env scrubbing', :aggregate_failures, openapi: false do
       capture_scrubbed_runtime_env(
         'RACK_ENV' => 'production',
         'HEALTH_CHECK_TOKEN' => 'scrubbed-health-token'
@@ -410,7 +410,7 @@ def expected_featured_feeds
       )
     end
 
-    it 'returns non-cacheable xml feed errors when service generation fails', :aggregate_failures do
+    it 'returns non-cacheable feed errors when service generation fails', :aggregate_failures do
       unique_url = "#{feed_url}/service-error-xml"
       token = Html2rss::Web::Auth.generate_feed_token('admin', unique_url, strategy: 'faraday')
 
@@ -424,7 +424,7 @@ def expected_featured_feeds
       expect(last_response.body).to include('Internal Server Error')
     end
 
-    it 'returns non-cacheable json feed errors when service generation fails', :aggregate_failures do
+    it 'returns non-cacheable json feed errors when service generation fails', :aggregate_failures, openapi: false do
       unique_url = "#{feed_url}/service-error-json"
       token = Html2rss::Web::Auth.generate_feed_token('admin', unique_url, strategy: 'faraday')