Rename uiType to docsProvider and simplify documentation

Co-authored-by: unnoq <64189902+unnoq@users.noreply.github.com>

Author: Copilot

apps/content/docs/openapi/plugins/openapi-reference.md

@@ -46,7 +46,7 @@ To use Swagger UI instead of the default Scalar interface:
 import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
 
 const plugin = new OpenAPIReferencePlugin({
-  uiType: 'swagger', // Use Swagger UI instead of Scalar
+  docsProvider: 'swagger', // Use Swagger UI instead of Scalar
   schemaConverters: [
     new ZodToJsonSchemaConverter(),
   ],
@@ -63,52 +63,4 @@ const handler = new OpenAPIHandler(router, {
 })
 ```
 
-## Configuration Options
 
-### `uiType`
-
-- **Type:** `'scalar' | 'swagger'`
-- **Default:** `'scalar'`
-
-Choose which UI library to use for rendering the API reference documentation.
-
-### `docsConfig`
-
-Pass additional configuration to the UI library:
-
-```ts
-const swaggerPlugin = new OpenAPIReferencePlugin({
-  uiType: 'swagger',
-  docsConfig: {
-    // Swagger UI specific options
-    tryItOutEnabled: true,
-    deepLinking: true,
-    // ... other Swagger UI options
-  }
-})
-```
-
-For Scalar:
-
-```ts
-const scalarPlugin = new OpenAPIReferencePlugin({
-  uiType: 'scalar', // or omit (default)
-  docsConfig: {
-    // Scalar specific options
-    hideDownloadButton: true,
-    // ... other Scalar options
-  }
-})
-```
-
-### Custom CDN URLs
-
-You can customize the CDN URLs for the UI libraries:
-
-```ts
-const plugin = new OpenAPIReferencePlugin({
-  uiType: 'swagger',
-  docsScriptUrl: 'https://your-cdn.com/swagger-ui-bundle.js',
-  docsCssUrl: 'https://your-cdn.com/swagger-ui.css',
-})
-```

packages/openapi/src/plugins/openapi-reference.test.ts

@@ -129,12 +129,12 @@ describe('openAPIReferencePlugin', () => {
     expect(await response!.text()).toContain('__SOME_VALUE__')
   })
 
-  it('should serve swagger UI when uiType is swagger', async () => {
+  it('should serve swagger UI when docsProvider is swagger', async () => {
     const handler = new OpenAPIHandler(router, {
       plugins: [
         new OpenAPIReferencePlugin({
           schemaConverters: [jsonSchemaConverter],
-          uiType: 'swagger',
+          docsProvider: 'swagger',
         }),
       ],
     })
@@ -152,12 +152,12 @@ describe('openAPIReferencePlugin', () => {
     expect(html).not.toContain('Scalar')
   })
 
-  it('should serve scalar UI when uiType is scalar (default)', async () => {
+  it('should serve scalar UI when docsProvider is scalar (default)', async () => {
     const handler = new OpenAPIHandler(router, {
       plugins: [
         new OpenAPIReferencePlugin({
           schemaConverters: [jsonSchemaConverter],
-          uiType: 'scalar',
+          docsProvider: 'scalar',
         }),
       ],
     })
@@ -182,7 +182,7 @@ describe('openAPIReferencePlugin', () => {
       plugins: [
         new OpenAPIReferencePlugin({
           schemaConverters: [jsonSchemaConverter],
-          uiType: 'swagger',
+          docsProvider: 'swagger',
           docsScriptUrl: customScriptUrl,
           docsCssUrl: customCssUrl,
         }),
@@ -204,7 +204,7 @@ describe('openAPIReferencePlugin', () => {
       plugins: [
         new OpenAPIReferencePlugin({
           schemaConverters: [jsonSchemaConverter],
-          uiType: 'swagger',
+          docsProvider: 'swagger',
           docsConfig: async () => ({
             tryItOutEnabled: true,
             customOption: '__SWAGGER_CONFIG__',

packages/openapi/src/plugins/openapi-reference.ts

@@ -39,7 +39,7 @@ export interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAP
    *
    * @default 'scalar'
    */
-  uiType?: 'scalar' | 'swagger'
+  docsProvider?: 'scalar' | 'swagger'
 
   /**
    * Arbitrary configuration object for the UI.
@@ -78,7 +78,7 @@ export interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAP
     scriptUrl: string,
     config: Record<string, unknown> | undefined,
     spec: OpenAPI.Document,
-    uiType: 'scalar' | 'swagger',
+    docsProvider: 'scalar' | 'swagger',
     cssUrl?: string
   ) => string
 }
@@ -90,7 +90,7 @@ export class OpenAPIReferencePlugin<T extends Context> implements StandardHandle
   private readonly docsPath: Exclude<OpenAPIReferencePluginOptions<T>['docsPath'], undefined>
   private readonly docsTitle: Exclude<OpenAPIReferencePluginOptions<T>['docsTitle'], undefined>
   private readonly docsHead: Exclude<OpenAPIReferencePluginOptions<T>['docsHead'], undefined>
-  private readonly uiType: Exclude<OpenAPIReferencePluginOptions<T>['uiType'], undefined>
+  private readonly docsProvider: Exclude<OpenAPIReferencePluginOptions<T>['docsProvider'], undefined>
   private readonly docsScriptUrl: Exclude<OpenAPIReferencePluginOptions<T>['docsScriptUrl'], undefined>
   private readonly docsCssUrl: OpenAPIReferencePluginOptions<T>['docsCssUrl']
   private readonly docsConfig: OpenAPIReferencePluginOptions<T>['docsConfig']
@@ -101,18 +101,18 @@ export class OpenAPIReferencePlugin<T extends Context> implements StandardHandle
     this.docsPath = options.docsPath ?? '/'
     this.docsTitle = options.docsTitle ?? 'API Reference'
     this.docsConfig = options.docsConfig ?? undefined
-    this.uiType = options.uiType ?? 'scalar'
+    this.docsProvider = options.docsProvider ?? 'scalar'
 
     // Set default script URL based on UI type
     this.docsScriptUrl = options.docsScriptUrl ?? (
-      this.uiType === 'swagger'
+      this.docsProvider === 'swagger'
         ? 'https://unpkg.com/swagger-ui-dist@5.17.14/swagger-ui-bundle.js'
         : 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'
     )
 
     // Set CSS URL for Swagger UI
     this.docsCssUrl = options.docsCssUrl ?? (
-      this.uiType === 'swagger'
+      this.docsProvider === 'swagger'
         ? 'https://unpkg.com/swagger-ui-dist@5.17.14/swagger-ui.css'
         : undefined
     )
@@ -123,8 +123,8 @@ export class OpenAPIReferencePlugin<T extends Context> implements StandardHandle
 
     const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
 
-    this.renderDocsHtml = options.renderDocsHtml ?? ((specUrl, title, head, scriptUrl, config, spec, uiType, cssUrl) => {
-      if (uiType === 'swagger') {
+    this.renderDocsHtml = options.renderDocsHtml ?? ((specUrl, title, head, scriptUrl, config, spec, docsProvider, cssUrl) => {
+      if (docsProvider === 'swagger') {
         // Swagger UI configuration
         const swaggerConfig = {
           dom_id: '#app',
@@ -237,7 +237,7 @@ export class OpenAPIReferencePlugin<T extends Context> implements StandardHandle
           await value(this.docsScriptUrl, options),
           await value(this.docsConfig, options),
           await generateSpec(),
-          this.uiType,
+          this.docsProvider,
           this.docsCssUrl ? await value(this.docsCssUrl, options) : undefined,
         )