Add possibility to hook into the config initialization. #2590

Danielku15 · 2023-01-19T12:14:40Z

To register custom plugins and customize the Swagger UI it is currently required to provide an own index.html. This has the negative impact of keeping it up-to-date with Swashbuckle.

This PR extends the default index.html with a new way of hooking into the Swagger UI setup allowing devs to register plugins and change settings within a custom injected JavaScript acting as entry point.

I extended also the docs to show some basics on how the Plugin API and React can be used in such a setup to customize the UI even further. We have been doing this for quite a while using a custom index.html but having such a feature by-default would bring benefit to everyone (and we do not need to maintain it once per API 😁).

esbenbach · 2023-09-29T08:30:36Z

@domaindrivendev Any chance of this making it into the next version? It looks like a pretty neat/clean addition to the UI configuration to me.

…ashbuckle#1

martincostello · 2024-04-13T08:42:13Z

Thanks for contributing - if you'd like to continue with this pull request, please rebase against the default branch to pick up our new CI.

Danielku15 · 2024-04-13T13:28:31Z

@martincostello Rebase done 😉

codecov-commenter · 2024-04-13T13:32:41Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 91.66%. Comparing base (9e77996) to head (0e225c0).

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2590   +/-   ##
=======================================
  Coverage   91.66%   91.66%           
=======================================
  Files          91       91           
  Lines        3010     3010           
  Branches      517      517           
=======================================
  Hits         2759     2759           
  Misses        251      251

Flag	Coverage Δ
Linux	`91.66% <ø> (ø)`
Windows	`91.66% <ø> (ø)`
macOS	`91.66% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

martincostello · 2024-04-13T13:31:55Z

README.md

@@ -1341,6 +1342,78 @@ app.UseSwaggerUI(c =>
 });
 ```

+### Change Swagger UI Config ###
+
+Swagger UI has a big variety of options and a mighty plugin API allowing customizations. 


Suggested change

Swagger UI has a big variety of options and a mighty plugin API allowing customizations.

Swagger UI has a large variety of options and a mighty plugin API allowing customizations.

martincostello · 2024-04-13T13:32:13Z

README.md

+Swagger UI has a big variety of options and a mighty plugin API allowing customizations. 
+To customize the Swagger UI (and OAuth) configuration objects before they are passed into the Swagger UI initialization,
+inject a custom JavaScript file which defines a global function with the following signature.
+In many cases this feature allows to avoid using a custom `index.html` in your project.


Suggested change

In many cases this feature allows to avoid using a custom `index.html` in your project.

In many cases this feature allows you to avoid using a custom `index.html` in your project.

martincostello · 2024-04-13T13:33:00Z

README.md

+function initConfig(configObject, oauthConfigObject) { }
+```
+
+Through this mechanism any options that Swagger UI supports can be set and also plugins can be registered. 


Suggested change

Through this mechanism any options that Swagger UI supports can be set and also plugins can be registered.

Through this mechanism any options that Swagger UI supports can be set, and also plugins can be registered.

martincostello · 2024-04-13T13:33:13Z

README.md

+
+Through this mechanism any options that Swagger UI supports can be set and also plugins can be registered. 
+Swagger UI is written with React so it can be a bit tricky to write custom components. 
+Here a full example which adds a custom section to the parameters of all operations:


Suggested change

Here a full example which adds a custom section to the parameters of all operations:

Here is a full example which adds a custom section to the parameters of all operations:

martincostello · 2024-04-13T13:33:26Z

README.md

+// swagger-ui.js
+// https://swagger.io/docs/open-source-tools/swagger-ui/customization/plugin-api/
+function configInit(config) {
+    if(!config.plugins) {


Suggested change

if(!config.plugins) {

if (!config.plugins) {

martincostello · 2024-04-13T13:36:00Z

README.md

+                return system.React.createElement('div',
+                    { className: "parameters-wrap"},
+                    system.React.createElement(CustomOperationDetails, props),
+                    system.React.createElement(Original, props)
+                );


This example looks out-of-date compared to the example in the non-obsolete React documentation.

martincostello · 2024-04-13T13:36:44Z

README.md

+app.UseSwaggerUI(options = > 
+{
+    options.InjectJavascript("swagger-ui.js");
+});
+```
+
+


Suggested change

app.UseSwaggerUI(options = >

{

options.InjectJavascript("swagger-ui.js");

});

```

app.UseSwaggerUI(options => options.InjectJavascript("swagger-ui.js"));

martincostello · 2024-04-13T13:36:57Z

src/Swashbuckle.AspNetCore.SwaggerUI/index.html

@@ -102,6 +102,11 @@
            if (interceptors.ResponseInterceptorFunction)
                configObject.responseInterceptor = parseFunction(interceptors.ResponseInterceptorFunction);

+            // Allow adjusting config through injected JavaScript files
+            if(typeof initConfig === "function") {


Suggested change

if(typeof initConfig === "function") {

if (typeof initConfig === "function") {

martincostello · 2024-04-13T13:38:22Z

src/Swashbuckle.AspNetCore.SwaggerUI/index.html

@@ -102,6 +102,11 @@
            if (interceptors.ResponseInterceptorFunction)
                configObject.responseInterceptor = parseFunction(interceptors.ResponseInterceptorFunction);

+            // Allow adjusting config through injected JavaScript files
+            if(typeof initConfig === "function") {


Is there a better way of hooking this up as a global that's more robust and/or more likely to not pollute with any existing objects (e.g. what if it was called swashbuckleInitConfig for instance)?

martincostello · 2024-04-13T13:38:45Z

src/Swashbuckle.AspNetCore.SwaggerUI/index.html

Is there a sample and/or integration test that can be updated to demonstrate this somehow?

Havunen added a commit to Havunen/DotSwashbuckle2 that referenced this pull request Feb 12, 2024

porting domaindrivendev/Swashbuckle.AspNetCore#2590 for Havunen/DotSw…

ea2879c

…ashbuckle#1

Havunen added a commit to Havunen/DotSwashbuckle that referenced this pull request Feb 18, 2024

porting domaindrivendev#2590 for #1 credits @Danielku15

eb62317

Danielku15 force-pushed the feature/config-init branch from 672d1fd to a79bf7f Compare April 13, 2024 13:25

Add possibility to hook into the config initialization.

0e225c0

Danielku15 force-pushed the feature/config-init branch from a79bf7f to 0e225c0 Compare April 13, 2024 13:27

martincostello reviewed Apr 13, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add possibility to hook into the config initialization. #2590

Add possibility to hook into the config initialization. #2590

Danielku15 commented Jan 19, 2023

esbenbach commented Sep 29, 2023

martincostello commented Apr 13, 2024

Danielku15 commented Apr 13, 2024

codecov-commenter commented Apr 13, 2024 •

edited

martincostello Apr 13, 2024

martincostello Apr 13, 2024

martincostello Apr 13, 2024

martincostello Apr 13, 2024

martincostello Apr 13, 2024

martincostello Apr 13, 2024

martincostello Apr 13, 2024

martincostello Apr 13, 2024

martincostello Apr 13, 2024

martincostello Apr 13, 2024

	Swagger UI has a big variety of options and a mighty plugin API allowing customizations.
	Swagger UI has a large variety of options and a mighty plugin API allowing customizations.

	In many cases this feature allows to avoid using a custom `index.html` in your project.
	In many cases this feature allows you to avoid using a custom `index.html` in your project.

	Through this mechanism any options that Swagger UI supports can be set and also plugins can be registered.
	Through this mechanism any options that Swagger UI supports can be set, and also plugins can be registered.

	Here a full example which adds a custom section to the parameters of all operations:
	Here is a full example which adds a custom section to the parameters of all operations:

	if(typeof initConfig === "function") {
	if (typeof initConfig === "function") {

Add possibility to hook into the config initialization. #2590

Are you sure you want to change the base?

Add possibility to hook into the config initialization. #2590

Conversation

Danielku15 commented Jan 19, 2023

esbenbach commented Sep 29, 2023

martincostello commented Apr 13, 2024

Danielku15 commented Apr 13, 2024

codecov-commenter commented Apr 13, 2024 • edited

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov-commenter commented Apr 13, 2024 •

edited