Announcing Scribe v4.28

Scribe v4.28 provides more UI alternatives, and a number of useful features to make configuration easier.

Bring your own UI

You can now plug in any (in theory, at least) external client-side UI, such as Scalar. How does this work?

• Scribe generates a basic page that has two key things: a URL to your OpenAPI spec (which Scribe just generated), and a URL to the external JS and CSS.
• When the page is rendered, it fetches the content of the OpenAPI spec and renders it client-side.

For details on usage, see the config reference.

note

Using external UIs means that a bunch of Scribe output features will have no effect. These include:

• appending files
• group sorting
• example languages
• the logo config (as of v4.29, this now works in some UIs)
• the try_it_out config (as of v4.29, this now works in some UIs)
• the last_updated config

Configurable strategies

Sometimes you want to disable a certain strategy for a specific endpoint (for instance, if Scribe is generating incorrect information for that route). In the past, your only option was to remove it from your strategies array, meaning it would be disabled for all endpoints.

No more! This release contains a few features that make this doable.

• First, the new tuple format allows for you to pass settings to a strategy. A tuple is an array with two elements; the first is the strategy class, and the second is the settings array. Note that the simple "class name" format is still supported.

For instance, you can configure response calls to only be used on certain endpoints, by passing a settings array with a key named only:

'responses' => [
  Strategies\Responses\UseResponseAttributes::class,
  [
    Strategies\Responses\ResponseCalls::class,
    ['only' => ['GET *']],
  ]
],

• ...which brings us to the second feature: the only and except settings, which are automatically supported by all strategies (including your existing custom strategies. These allow you to specify the routes you want the strategy to be applied to, or not be applied to. Examples:

'bodyParameters' => [
  [
    Strategies\BodyParameters\GetFromInlineValidator::class,
    ['except' => ['POST /special-endpoint']],
  ],
  [
    App\Docs\Strategies\SomeCoolStuff::class,
    ['only' => ['POST /cool-endpoint']],
  ],
],

note

This means that, going forward, the configuration in apply.response_calls is now expressed in the response call settings. The old format is still supported, though.

• Thirdly, the new override strategy allows you to easily override returned values. This is a simple way to say "merge these values into the result of other strategies", without having to write a whole strategy class. The override strategy is also specified as a tuple. A common use case is for adding headers:

'headers' => [
  Strategies\Responses\UseHeaderAttribute::class,
  [
    'override',
    [
      'Content-Type' => 'application/json',
      'Accept' => 'application/json',
    ],
  ]
],

• Better route matching: Route matching now works with both method and URL. Previously, in you could only specify route name or URL. Now you can also specify "GET /path" or "GET path" or even "GET pa*".

New config format (beta)

• New config format: In an effort to simplify the config file and surface the most useful items, we're trying out a new config format which should be the default in v5. Unfortunately, there's no auto-migrate option, but it only takes 5 minutes to migrate. It's still a bit rough around the edges for now, but you can try it out: run php artisan vendor:publish scribe-config-next, then copy your settings from the old file, and rename the files.