v1.0 roadmap

[romalytvynenko]

Hey!

Last week, I released v0.12.x. This release is meant to gather feedback on the experimental configuration API and finalize it before v1.0.

In this discussion, I want to outline the plans for v1.0 to make the roadmap clear and transparent.

Here are the key things I plan to finalize before tagging v1.0, along with some thoughts on backward compatibility.

Backward Compatibility

While I want to improve Scramble’s APIs, I recognize that the library has been in v0.x for a long time, and many of you rely on the current APIs.

For v1.0, my goal is to preserve the existing APIs as much as possible to avoid breaking changes. There will be some deprecations and possibly minor breaking changes, but I’ll try to minimize them.

Before v1.0, all new APIs will be released as experimental so I can gather feedback. "Experimental API" means changes may still occur between patch versions (0.12.x and 0.12.y).

Configuration

With support for multiple API documents in a single project, it became clear that Scramble's configuration needs an update. Right now, configuration is global, making it unclear how to manage multiple API documents effectively.

public function boot()
{
    Scramble::configure() // returns config object for the default API
	      ->expose(...) // define documented routes (added in 0.12.x)
	      ->withDocumentTransformers(...) // modify the OpenAPI document (added in 0.12.x)
	      ->withOperationTransformers(...) // modify operations (added in 0.12.x)
	      ->withSchemaTransformers(...) // modify schemas
	      ->withParametersExtractors(...)
	      ->withConfig() // partial configuration
	      ->useConfig() // full configuration
	      ...

	  Scramble::registerApi('v2') // registers an API and returns a config object
	      ->expose(...)
	      ...
}

This was introduced in v0.12.0 and is ready for you to try!

Extensions

As Scramble evolved, the need for extension points became clearer. There should be a way to modify Scramble’s behavior by registering custom extensions before or after specific ones.

For v1.0, I plan to introduce these extension points:

• Document transformation – Modify the final OpenAPI document. In v0.x, you could only have one document transformer. In v1.0, multiple transformers can be applied sequentially.
• Operation transformation – This is what the current OperationExtension does.
• Schema transformation – A new extension point for modifying schemas in the OpenAPI document.
• Parameter extraction – Customize how Scramble extracts operation parameters for documentation.

Each transformer will receive the entity it modifies (document, operation, or schema) along with context information. For example, an operation transformer will get the route, configuration, and other relevant details.

You will also be able to control the order of extensions when registering them, including placing them before Scramble’s built-in extensions.

public function boot()
{
    Scramble::configure()
        ->withOperationTransformers(function (OperationTransformers $transformers) {
            $transformers
                ->prepend(HandleControllerBindingsTransformer::class)
                ->append([
                    AddRateLimitHeadersTransformer::class,
                    AddLocalizationHeadersTransformer::class,
                ]);
        });
}

These extensions (except schema transformation) are available now in v0.12.x as experimental!

Full OpenAPI 3.1.0 Support

v1.0 will fully support OpenAPI 3.1.0, allowing you to document everything the specification offers.

For example, you’ll be able to document callbacks, links, custom authentication, and more—things Scramble currently doesn’t handle.

Attributes

With more people using Scramble, it became clear that there should be an easy way to manually override generated documentation. PHP attributes solve this well by allowing modifications at the route level.

You should be able to redefine parameters, request bodies, responses, etc.

In v0.12.x, I introduced five new attributes for defining request parameters:

• #[QueryParameter]
• #[HeaderParameter]
• #[CookieParameter]
• #[PathParameter]
• #[BodyParameter]

What’s still missing:

• A way to manually document possible responses
• A way to ignore parameters
• Maybe more?

Support for Closure-Based Routes

Right now, Scramble only documents routes defined in controllers. For v1.0, I’d like to add support for closure-based routes as well.

Caching

Generating the OpenAPI document is resource-intensive because Scramble needs to parse a lot of PHP code into an AST and analyze it. Caching will help reduce resource usage and avoid unnecessary re-analysis.

Ideally, only changed files should be re-analyzed between documentation generations. However, this is complex, so simpler caching strategies may be needed.

Thoughts?

So that is the v1.0 roadmap.

Is there something missing? Is something highlighted here resonates with you?

Let me know what you think!

[depsimon]

Roadmap looks great!

I personnaly don't mind breaking changes, so backward compatibility is not required in my case.

Not sure it should be in the roadmap, but one thing that could be great to work on is the demos.

• Add a link to the demo in the sidebar of the docs
• Enrich the demo repo with more real-life use-cases (FormRequests, Attributed, docblocks, File Uploads, etc..)
• Perhaps multiple demos to showcase multiple cases (multi schema)
• From schema to Laravel code; it'd be incredible to have some schema -> code examples

All this could be used as the subject of the screencasts to make it worth.

[romalytvynenko]

Awesome, thank you!

Can you please elaborate on "From schema to Laravel code; it'd be incredible to have some schema -> code examples"?

[depsimon]

Thinking about it again, it sounds silly.

The idea was that when you want to implement a specific Schema, you'd get examples of how to do it in Laravel + Scramble.

I think it can inspire users, and show them how to implement some common cases with Laravel + Scramble. It's like lightweight demos if you want.

Just tried to do a simple example, but it's actually quite complicated to extract an excerpt of a schema due to the refs.

So perhaps doing the reverse makes more sense?

Like instead of full-featured demo/examples repos, just share the relevant code snippets (route, controller, FormRequest) with the resulting schema (or the relevant parts of the schema)

[romalytvynenko]

This sounds awesome! I will definitely improve the docs this way, thanks!

[Shadercloud]

I think there should be something similar to a Document Transformer that allows you to format that overall JSON output. For example if you want to insert attrbrary fields. Somewhere around here: https://github.com/dedoc/scramble/blob/main/src/Support/Generator/OpenApi.php#L118 passes the $results and the OpenApi document to an Output Transformer, then users can make an extension to basically do anything they need.

This below sounds like a good idea:

For v1.0, my goal is to preserve the existing APIs as much as possible to avoid breaking changes. There will be some deprecations and possibly minor breaking changes, but I’ll try to minimize them.

You could just stop documenting the old APIs; while not actively removing or breaking the old functionality.

[romalytvynenko]

if you want to insert attrbrary fields

What is the use case?

I think a document transformer for this reason should be enough. I believe something that is not a part of Open API spec should not be very easy to do via Scramble (as there won't be any limits of the possible API surface).

[Shadercloud]

In my case I'm only using the JSON aspect of Scramble, as my project as in Vue, so I'm using a Vue viewer (https://github.com/scalar/scalar/) to display the output.

As noted in my other dicussion (#718); in this case "tags" was missing from the Scramble JSON. While the Scamble frontend does not support viewing tag descriptions; the Vue viewer does already.

There may be other fields that one might want to add into the JSON that is supported by some other OpenAPI viewer. (Maybe even features that are outside or new in the OpenAPI specs)

With the ability to arbitrarily format the JSON output one could just customize it as needs must and continue with their project as opposed to request the fields be added to Scramble as a whole.

[romalytvynenko]

@Shadercloud that will be covered by full OpenAPI 3.1.0 specification

[mariosvasiliou]

Hello @romalytvynenko and thank you for your work.
We have tried your packages, and they are pretty good, but we have some issues, so I am suggesting some improvements.
I haven't upgraded yet to the 0.12.x version and made the applicable changes so perhaps some of my suggestions are already fixed.

1. Ability to get authorization token from overview and use it automatically (prefilled) on next requests.
2. The biggest problem is performance, we have many APIs, and loading all at once is not efficient at all and causes crashes if we do not increase the PHP memory limit. I don't know if that is fixed with groups you have added recently but it would be great if you eager load API information on click for each page or load only the current group.
3. A simpler way to add custom response classes
4. A simpler way to ignore classes, perhaps on config?

[romalytvynenko]

The biggest problem is performance, we have many APIs

I'd really like to fix the performance! If it's possible to give me access to the slow projects source (temporary add me as a contributor), I'd be happy to optimize Scramble for you – feel free to reach out to [email protected].

[romalytvynenko]

For 3 and 4 I'd need a specific examples

[Shadercloud]

I feel like the performance issue should just be fixed by caching. It's not reasonable to assume a complete API documenation should be generated on the fly with every request (that is never going to be fast on a larger project with many endpoints)