|
1 | | -# Configuration and Customization of `Swashbuckle.AspNetCore.ReDoc` |
2 | | - |
3 | | -## Change Relative Path to the UI |
4 | | - |
5 | | -By default, the Redoc UI will be exposed at `/api-docs`. If necessary, you can alter this when enabling the Redoc middleware: |
6 | | - |
7 | | -<!-- markdownlint-disable MD031 MD033 --> |
8 | | -<!-- snippet: Redoc-RoutePrefix --> |
9 | | -<a id='snippet-Redoc-RoutePrefix'></a> |
10 | | -```cs |
11 | | -app.UseReDoc(options => |
12 | | -{ |
13 | | - options.RoutePrefix = "docs"; |
14 | | -}); |
15 | | -``` |
16 | | -<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L142-L147' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-RoutePrefix' title='Start of snippet'>anchor</a></sup> |
17 | | -<!-- endSnippet --> |
18 | | -<!-- markdownlint-enable MD031 MD033 --> |
19 | | - |
20 | | -## Change Document Title |
21 | | - |
22 | | -By default, the Redoc UI will have a generic document title. You can alter this when enabling the Redoc middleware: |
23 | | - |
24 | | -<!-- markdownlint-disable MD031 MD033 --> |
25 | | -<!-- snippet: Redoc-DocumentTitle --> |
26 | | -<a id='snippet-Redoc-DocumentTitle'></a> |
27 | | -```cs |
28 | | -app.UseReDoc(options => |
29 | | -{ |
30 | | - options.DocumentTitle = "My API Docs"; |
31 | | -}); |
32 | | -``` |
33 | | -<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L149-L154' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-DocumentTitle' title='Start of snippet'>anchor</a></sup> |
34 | | -<!-- endSnippet --> |
35 | | -<!-- markdownlint-enable MD031 MD033 --> |
36 | | - |
37 | | -## Apply Redoc Parameters |
38 | | - |
39 | | -Redoc ships with its own set of configuration parameters, all described [in the Redoc documentation][redoc-options]. |
40 | | -In Swashbuckle.AspNetCore, most of these are surfaced through the Redoc middleware options: |
41 | | - |
42 | | -<!-- markdownlint-disable MD031 MD033 --> |
43 | | -<!-- snippet: Redoc-CustomOptions --> |
44 | | -<a id='snippet-Redoc-CustomOptions'></a> |
45 | | -```cs |
46 | | -app.UseReDoc(options => |
47 | | -{ |
48 | | - options.SpecUrl("/v1/swagger.json"); |
49 | | - options.EnableUntrustedSpec(); |
50 | | - options.ScrollYOffset(10); |
51 | | - options.HideHostname(); |
52 | | - options.HideDownloadButton(); |
53 | | - options.ExpandResponses("200,201"); |
54 | | - options.RequiredPropsFirst(); |
55 | | - options.NoAutoAuth(); |
56 | | - options.PathInMiddlePanel(); |
57 | | - options.HideLoading(); |
58 | | - options.NativeScrollbars(); |
59 | | - options.DisableSearch(); |
60 | | - options.OnlyRequiredInSamples(); |
61 | | - options.SortPropsAlphabetically(); |
62 | | -}); |
63 | | -``` |
64 | | -<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L156-L174' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-CustomOptions' title='Start of snippet'>anchor</a></sup> |
65 | | -<!-- endSnippet --> |
66 | | -<!-- markdownlint-enable MD031 MD033 --> |
67 | | - |
68 | | -> [!NOTE] |
69 | | -> Using `options.SpecUrl("/v1/swagger.json")` multiple times within the same `UseReDoc(...)` will not add multiple URLs. |
70 | | -
|
71 | | -## Inject Custom CSS |
72 | | - |
73 | | -To tweak the look and feel, you can inject additional CSS stylesheets by adding them to your `wwwroot` folder and specifying |
74 | | -the relative paths in the middleware options: |
75 | | - |
76 | | -<!-- markdownlint-disable MD031 MD033 --> |
77 | | -<!-- snippet: Redoc-CustomCSS --> |
78 | | -<a id='snippet-Redoc-CustomCSS'></a> |
79 | | -```cs |
80 | | -app.UseReDoc(options => |
81 | | -{ |
82 | | - options.InjectStylesheet("/redoc/custom.css"); |
83 | | -}); |
84 | | -``` |
85 | | -<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L176-L181' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-CustomCSS' title='Start of snippet'>anchor</a></sup> |
86 | | -<!-- endSnippet --> |
87 | | -<!-- markdownlint-enable MD031 MD033 --> |
88 | | - |
89 | | -It is also possible to modify the theme by using the `AdditionalItems` property. More information can be found |
90 | | -[in the Redoc documentation][redoc-options]. |
91 | | - |
92 | | -<!-- markdownlint-disable MD031 MD033 --> |
93 | | -<!-- snippet: Redoc-ModifyTheme --> |
94 | | -<a id='snippet-Redoc-ModifyTheme'></a> |
95 | | -```cs |
96 | | -app.UseReDoc(options => |
97 | | -{ |
98 | | - options.ConfigObject.AdditionalItems = new Dictionary<string, object> |
99 | | - { |
100 | | - // Configured additional options |
101 | | - }; |
102 | | -}); |
103 | | -``` |
104 | | -<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L183-L191' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-ModifyTheme' title='Start of snippet'>anchor</a></sup> |
105 | | -<!-- endSnippet --> |
106 | | -<!-- markdownlint-enable MD031 MD033 --> |
107 | | - |
108 | | -## Customize index.html |
109 | | - |
110 | | -To customize the UI beyond the basic options listed above, you can provide your own version of the Redoc `index.html` page: |
111 | | - |
112 | | -<!-- markdownlint-disable MD031 MD033 --> |
113 | | -<!-- snippet: Redoc-CustomIndexHtml --> |
114 | | -<a id='snippet-Redoc-CustomIndexHtml'></a> |
115 | | -```cs |
116 | | -app.UseReDoc(options => |
117 | | -{ |
118 | | - options.IndexStream = () => typeof(Program).Assembly |
119 | | - .GetManifestResourceStream("CustomIndex.ReDoc.index.html"); // Requires file to be added as an embedded resource |
120 | | -}); |
121 | | -``` |
122 | | -<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L193-L199' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-CustomIndexHtml' title='Start of snippet'>anchor</a></sup> |
123 | | -<!-- endSnippet --> |
124 | | -<!-- markdownlint-enable MD031 MD033 --> |
125 | | - |
126 | | -```xml |
127 | | -<Project> |
128 | | - <ItemGroup> |
129 | | - <EmbeddedResource Include="CustomIndex.ReDoc.index.html" /> |
130 | | - </ItemGroup> |
131 | | -</Project> |
132 | | -``` |
133 | | - |
134 | | -> [!TIP] |
135 | | -> To get started, you should base your custom `index.html` on the [default version](../src/Swashbuckle.AspNetCore.ReDoc/index.html). |
136 | | -
|
137 | | -[redoc-options]: https://github.com/Redocly/redoc/blob/main/docs/deployment/html.md#the-redoc-object |
| 1 | +# Configuration and Customization of `Swashbuckle.AspNetCore.ReDoc` |
| 2 | + |
| 3 | +## Change Relative Path to the UI |
| 4 | + |
| 5 | +By default, the Redoc UI will be exposed at `/api-docs`. If necessary, you can alter this when enabling the Redoc middleware: |
| 6 | + |
| 7 | +<!-- markdownlint-disable MD031 MD033 --> |
| 8 | +<!-- snippet: Redoc-RoutePrefix --> |
| 9 | +<a id='snippet-Redoc-RoutePrefix'></a> |
| 10 | +```cs |
| 11 | +app.UseReDoc(options => |
| 12 | +{ |
| 13 | + options.RoutePrefix = "docs"; |
| 14 | +}); |
| 15 | +``` |
| 16 | +<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L142-L147' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-RoutePrefix' title='Start of snippet'>anchor</a></sup> |
| 17 | +<!-- endSnippet --> |
| 18 | +<!-- markdownlint-enable MD031 MD033 --> |
| 19 | + |
| 20 | +## Change Document Title |
| 21 | + |
| 22 | +By default, the Redoc UI will have a generic document title. You can alter this when enabling the Redoc middleware: |
| 23 | + |
| 24 | +<!-- markdownlint-disable MD031 MD033 --> |
| 25 | +<!-- snippet: Redoc-DocumentTitle --> |
| 26 | +<a id='snippet-Redoc-DocumentTitle'></a> |
| 27 | +```cs |
| 28 | +app.UseReDoc(options => |
| 29 | +{ |
| 30 | + options.DocumentTitle = "My API Docs"; |
| 31 | +}); |
| 32 | +``` |
| 33 | +<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L149-L154' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-DocumentTitle' title='Start of snippet'>anchor</a></sup> |
| 34 | +<!-- endSnippet --> |
| 35 | +<!-- markdownlint-enable MD031 MD033 --> |
| 36 | + |
| 37 | +## Apply Redoc Parameters |
| 38 | + |
| 39 | +Redoc ships with its own set of configuration parameters, all described [in the Redoc documentation][redoc-options]. |
| 40 | +In Swashbuckle.AspNetCore, most of these are surfaced through the Redoc middleware options: |
| 41 | + |
| 42 | +<!-- markdownlint-disable MD031 MD033 --> |
| 43 | +<!-- snippet: Redoc-CustomOptions --> |
| 44 | +<a id='snippet-Redoc-CustomOptions'></a> |
| 45 | +```cs |
| 46 | +app.UseReDoc(options => |
| 47 | +{ |
| 48 | + options.SpecUrl("/v1/swagger.json"); |
| 49 | + options.EnableUntrustedSpec(); |
| 50 | + options.ScrollYOffset(10); |
| 51 | + options.HideHostname(); |
| 52 | + options.HideDownloadButton(); |
| 53 | + options.ExpandResponses("200,201"); |
| 54 | + options.RequiredPropsFirst(); |
| 55 | + options.NoAutoAuth(); |
| 56 | + options.PathInMiddlePanel(); |
| 57 | + options.HideLoading(); |
| 58 | + options.NativeScrollbars(); |
| 59 | + options.DisableSearch(); |
| 60 | + options.OnlyRequiredInSamples(); |
| 61 | + options.SortPropsAlphabetically(); |
| 62 | +}); |
| 63 | +``` |
| 64 | +<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L156-L174' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-CustomOptions' title='Start of snippet'>anchor</a></sup> |
| 65 | +<!-- endSnippet --> |
| 66 | +<!-- markdownlint-enable MD031 MD033 --> |
| 67 | + |
| 68 | +> [!NOTE] |
| 69 | +> Using `options.SpecUrl("/v1/swagger.json")` multiple times within the same `UseReDoc(...)` will not add multiple URLs. |
| 70 | +
|
| 71 | +## Inject Custom CSS |
| 72 | + |
| 73 | +To tweak the look and feel, you can inject additional CSS stylesheets by adding them to your `wwwroot` folder and specifying |
| 74 | +the relative paths in the middleware options: |
| 75 | + |
| 76 | +<!-- markdownlint-disable MD031 MD033 --> |
| 77 | +<!-- snippet: Redoc-CustomCSS --> |
| 78 | +<a id='snippet-Redoc-CustomCSS'></a> |
| 79 | +```cs |
| 80 | +app.UseReDoc(options => |
| 81 | +{ |
| 82 | + options.InjectStylesheet("/redoc/custom.css"); |
| 83 | +}); |
| 84 | +``` |
| 85 | +<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L176-L181' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-CustomCSS' title='Start of snippet'>anchor</a></sup> |
| 86 | +<!-- endSnippet --> |
| 87 | +<!-- markdownlint-enable MD031 MD033 --> |
| 88 | + |
| 89 | +It is also possible to modify the theme by using the `AdditionalItems` property. More information can be found |
| 90 | +[in the Redoc documentation][redoc-options]. |
| 91 | + |
| 92 | +<!-- markdownlint-disable MD031 MD033 --> |
| 93 | +<!-- snippet: Redoc-ModifyTheme --> |
| 94 | +<a id='snippet-Redoc-ModifyTheme'></a> |
| 95 | +```cs |
| 96 | +app.UseReDoc(options => |
| 97 | +{ |
| 98 | + options.ConfigObject.AdditionalItems = new Dictionary<string, object> |
| 99 | + { |
| 100 | + // Configured additional options |
| 101 | + }; |
| 102 | +}); |
| 103 | +``` |
| 104 | +<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L183-L191' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-ModifyTheme' title='Start of snippet'>anchor</a></sup> |
| 105 | +<!-- endSnippet --> |
| 106 | +<!-- markdownlint-enable MD031 MD033 --> |
| 107 | + |
| 108 | +## Customize index.html |
| 109 | + |
| 110 | +To customize the UI beyond the basic options listed above, you can provide your own version of the Redoc `index.html` page: |
| 111 | + |
| 112 | +<!-- markdownlint-disable MD031 MD033 --> |
| 113 | +<!-- snippet: Redoc-CustomIndexHtml --> |
| 114 | +<a id='snippet-Redoc-CustomIndexHtml'></a> |
| 115 | +```cs |
| 116 | +app.UseReDoc(options => |
| 117 | +{ |
| 118 | + options.IndexStream = () => typeof(Program).Assembly |
| 119 | + .GetManifestResourceStream("CustomIndex.ReDoc.index.html"); // Requires file to be added as an embedded resource |
| 120 | +}); |
| 121 | +``` |
| 122 | +<sup><a href='/test/WebSites/DocumentationSnippets/WebApplicationExtensions.cs#L193-L199' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-CustomIndexHtml' title='Start of snippet'>anchor</a></sup> |
| 123 | +<!-- endSnippet --> |
| 124 | +<!-- markdownlint-enable MD031 MD033 --> |
| 125 | + |
| 126 | +```xml |
| 127 | +<Project> |
| 128 | + <ItemGroup> |
| 129 | + <EmbeddedResource Include="CustomIndex.ReDoc.index.html" /> |
| 130 | + </ItemGroup> |
| 131 | +</Project> |
| 132 | +``` |
| 133 | + |
| 134 | +> [!TIP] |
| 135 | +> To get started, you should base your custom `index.html` on the [default version](../src/Swashbuckle.AspNetCore.ReDoc/index.html). |
| 136 | +
|
| 137 | +## Use `MapReDoc` with endpoint routing |
| 138 | + |
| 139 | +`MapReDoc` is an endpoint-routing alternative to `UseReDoc`. The options API is the same, so all customization examples on this page also apply when using `MapReDoc`. |
| 140 | + |
| 141 | +<!-- markdownlint-disable MD031 MD033 --> |
| 142 | +<!-- snippet: Redoc-MapReDoc --> |
| 143 | +<a id='snippet-Redoc-MapReDoc'></a> |
| 144 | +```cs |
| 145 | +app.MapReDoc(); |
| 146 | +``` |
| 147 | +<sup><a href='/test/WebSites/WebApi.Map/Program.cs#L33-L35' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-MapReDoc' title='Start of snippet'>anchor</a></sup> |
| 148 | +<!-- endSnippet --> |
| 149 | +<!-- markdownlint-enable MD031 MD033 --> |
| 150 | + |
| 151 | +The main differences are: |
| 152 | + |
| 153 | +- **Use**ReDoc adds middleware directly to the request pipeline and returns `IApplicationBuilder`. |
| 154 | +- **Map**ReDoc maps ReDoc via endpoint routing and returns `IEndpointConventionBuilder`. |
| 155 | + |
| 156 | +- Because `MapReDoc` returns an endpoint convention builder, you can attach endpoint metadata/conventions (for example, authorization policies) directly to the mapped ReDoc endpoint. |
| 157 | + |
| 158 | +<!-- markdownlint-disable MD031 MD033 --> |
| 159 | +<!-- snippet: Redoc-MapReDoc-RequireAuthorization --> |
| 160 | +<a id='snippet-Redoc-MapReDoc-RequireAuthorization'></a> |
| 161 | +```cs |
| 162 | +app.MapReDoc("redoc-auth") |
| 163 | + .RequireAuthorization(); // Remember to also add RequireAuthorization to MapSwagger |
| 164 | +``` |
| 165 | +<sup><a href='/test/WebSites/WebApi.Map/Program.cs#L37-L40' title='Snippet source file'>snippet source</a> | <a href='#snippet-Redoc-MapReDoc-RequireAuthorization' title='Start of snippet'>anchor</a></sup> |
| 166 | +<!-- endSnippet --> |
| 167 | +<!-- markdownlint-enable MD031 MD033 --> |
| 168 | + |
| 169 | +[redoc-options]: https://github.com/Redocly/redoc/blob/main/docs/deployment/html.md#the-redoc-object |
0 commit comments