feat(openapi): Add Swagger UI support to OpenAPI Reference Plugin by Copilot · Pull Request #904 · middleapi/orpc

Copilot · 2025-08-20T08:54:26Z

The OpenAPI Reference Plugin now supports both Scalar and Swagger UI for rendering API documentation, giving developers the flexibility to choose their preferred interface.

Changes Made

New Configuration Options

docsProvider: Choose between 'scalar' (default) or 'swagger' - renamed from uiType for better consistency with the existing docs* naming pattern
docsCssUrl: CSS URL for Swagger UI styling (automatically configured)
Enhanced docsScriptUrl with smart defaults based on UI type

Implementation Details

The plugin automatically configures the appropriate CDN URLs and HTML structure based on the selected UI type:

Scalar (default):

Script: https://cdn.jsdelivr.net/npm/@scalar/api-reference
Initialization: Scalar.createApiReference()

Swagger UI:

Script: https://unpkg.com/swagger-ui-dist@5.17.14/swagger-ui-bundle.js
CSS: https://unpkg.com/swagger-ui-dist@5.17.14/swagger-ui.css
Initialization: SwaggerUIBundle()

Usage Examples

Using Swagger UI:

import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'

const plugin = new OpenAPIReferencePlugin({
  docsProvider: 'swagger', // Use Swagger UI
  schemaConverters: [new ZodToJsonSchemaConverter()],
  specGenerateOptions: {
    info: {
      title: 'My API',
      version: '1.0.0',
    },
  },
})

Using Scalar (default - no changes needed):

const plugin = new OpenAPIReferencePlugin({
  // docsProvider defaults to 'scalar'
  schemaConverters: [new ZodToJsonSchemaConverter()],
  specGenerateOptions: {
    info: {
      title: 'My API', 
      version: '1.0.0',
    },
  },
})

Documentation Improvements

Simplified the documentation by focusing on essential usage patterns and removing verbose configuration sections for better readability.

Backward Compatibility

This change includes a breaking change: the uiType option has been renamed to docsProvider for better API consistency. However, all functionality remains the same, and the default behavior is unchanged (Scalar UI).

Testing

Updated comprehensive test coverage including:

HTML generation verification for both UI types
Script and CSS URL configuration testing
Custom configuration support validation
All existing tests continue to pass with the new API

Fixes #903.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Copilot · 2025-08-20T08:54:27Z

@unnoq 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.

vercel · 2025-08-20T08:54:34Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
orpc	Ready	Preview	Comment	Aug 21, 2025 2:51am

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

dinwwwh · 2025-08-20T09:37:18Z

+import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
+
+const plugin = new OpenAPIReferencePlugin({
+  uiType: 'swagger', // Use Swagger UI instead of Scalar


There is any better option name for uiType ? docsProvider ? docsType? ...

@copilot use better option name, make it more consistentcy

I've renamed uiType to docsProvider for better consistency with the existing docs* naming pattern in the API. This change has been applied throughout the codebase including the TypeScript interface, implementation, tests, and documentation. Commit: 0e78373

dinwwwh · 2025-08-21T01:39:16Z

+import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
+
+const plugin = new OpenAPIReferencePlugin({
+  uiType: 'swagger', // Use Swagger UI instead of Scalar


@copilot use better option name, make it more consistentcy

dinwwwh · 2025-08-21T01:40:29Z

+
+## Configuration Options
+
+### `uiType`


@copilot do not add extra any section - the first docs is enough now.

I've simplified the documentation by removing the extra "Configuration Options" section and its subsections. The documentation now focuses on the essential setup and Swagger UI usage examples without the detailed configuration sections. Commit: 0e78373

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

dinwwwh · 2025-08-21T01:59:23Z

 By default, the API reference client is served at the root path (`/`), and the OpenAPI specification is available at `/spec.json`. You can customize these paths by providing the `docsPath` and `specPath` options.
 :::
+
+## Using Swagger UI


@copilot remove this section, only mention docsProvider in Setup section is enough

dinwwwh · 2025-08-21T02:00:31Z

          await value(this.docsConfig, options),
          await generateSpec(),
+          this.docsProvider,
+          this.docsCssUrl ? await value(this.docsCssUrl, options) : undefined,


@copilot NO need condition here, just await value directly

coderabbitai · 2025-08-21T02:47:37Z

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Join our Discord community for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

Visit our Status Page to check the current availability of CodeRabbit.
Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

codecov · 2025-08-21T02:49:24Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

pkg-pr-new · 2025-08-21T02:50:11Z

More templates

@orpc/arktype

npm i https://pkg.pr.new/@orpc/arktype@904

@orpc/client

npm i https://pkg.pr.new/@orpc/client@904

@orpc/contract

npm i https://pkg.pr.new/@orpc/contract@904

@orpc/experimental-durable-event-iterator

npm i https://pkg.pr.new/@orpc/experimental-durable-event-iterator@904

@orpc/hey-api

npm i https://pkg.pr.new/@orpc/hey-api@904

@orpc/interop

npm i https://pkg.pr.new/@orpc/interop@904

@orpc/json-schema

npm i https://pkg.pr.new/@orpc/json-schema@904

@orpc/nest

npm i https://pkg.pr.new/@orpc/nest@904

@orpc/openapi

npm i https://pkg.pr.new/@orpc/openapi@904

@orpc/openapi-client

npm i https://pkg.pr.new/@orpc/openapi-client@904

@orpc/otel

npm i https://pkg.pr.new/@orpc/otel@904

@orpc/react

npm i https://pkg.pr.new/@orpc/react@904

@orpc/react-query

npm i https://pkg.pr.new/@orpc/react-query@904

@orpc/experimental-react-swr

npm i https://pkg.pr.new/@orpc/experimental-react-swr@904

@orpc/server

npm i https://pkg.pr.new/@orpc/server@904

@orpc/shared

npm i https://pkg.pr.new/@orpc/shared@904

@orpc/solid-query

npm i https://pkg.pr.new/@orpc/solid-query@904

@orpc/standard-server

npm i https://pkg.pr.new/@orpc/standard-server@904

@orpc/standard-server-aws-lambda

npm i https://pkg.pr.new/@orpc/standard-server-aws-lambda@904

@orpc/standard-server-fetch

npm i https://pkg.pr.new/@orpc/standard-server-fetch@904

@orpc/standard-server-node

npm i https://pkg.pr.new/@orpc/standard-server-node@904

@orpc/standard-server-peer

npm i https://pkg.pr.new/@orpc/standard-server-peer@904

@orpc/svelte-query

npm i https://pkg.pr.new/@orpc/svelte-query@904

@orpc/tanstack-query

npm i https://pkg.pr.new/@orpc/tanstack-query@904

@orpc/trpc

npm i https://pkg.pr.new/@orpc/trpc@904

@orpc/valibot

npm i https://pkg.pr.new/@orpc/valibot@904

@orpc/vue-colada

npm i https://pkg.pr.new/@orpc/vue-colada@904

@orpc/vue-query

npm i https://pkg.pr.new/@orpc/vue-query@904

@orpc/zod

npm i https://pkg.pr.new/@orpc/zod@904

commit: b910bb8

Initial plan

84e6e41

Copilot AI assigned Copilot and dinwwwh Aug 20, 2025

Copilot started work on behalf of dinwwwh August 20, 2025 08:54 View session

vercel Bot temporarily deployed to Preview August 20, 2025 08:59 Inactive

Add Swagger UI support to OpenAPI Reference Plugin

3e17621

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

vercel Bot temporarily deployed to Preview August 20, 2025 09:06 Inactive

Update documentation for Swagger UI support and fix linting issues

99f6cba

Copilot AI changed the title ~~[WIP] Support Swangger UI in OpenAPI Reference Plugin~~ feat: Add Swagger UI support to OpenAPI Reference Plugin Aug 20, 2025

Copilot AI requested a review from dinwwwh August 20, 2025 09:13

Copilot finished work on behalf of dinwwwh August 20, 2025 09:13

vercel Bot temporarily deployed to Preview August 20, 2025 09:16 Inactive

dinwwwh requested changes Aug 20, 2025

View reviewed changes

dinwwwh requested changes Aug 21, 2025

View reviewed changes

Copilot started work on behalf of dinwwwh August 21, 2025 01:41 View session

Rename uiType to docsProvider and simplify documentation

0e78373

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

Copilot AI changed the title ~~feat: Add Swagger UI support to OpenAPI Reference Plugin~~ feat: Add Swagger UI support to OpenAPI Reference Plugin with improved API naming Aug 21, 2025

Copilot AI requested a review from dinwwwh August 21, 2025 01:49

Copilot finished work on behalf of dinwwwh August 21, 2025 01:49

vercel Bot temporarily deployed to Preview August 21, 2025 01:52 Inactive

dinwwwh requested changes Aug 21, 2025

View reviewed changes

Copilot AI requested a review from dinwwwh August 21, 2025 02:01

improve

b910bb8

dinwwwh marked this pull request as ready for review August 21, 2025 02:49

dosubot Bot added the size:L This PR changes 100-499 lines, ignoring generated files. label Aug 21, 2025

vercel Bot temporarily deployed to Preview August 21, 2025 02:51 Inactive

dinwwwh approved these changes Aug 21, 2025

View reviewed changes

dosubot Bot added the lgtm This PR has been approved by a maintainer label Aug 21, 2025

dinwwwh changed the title ~~feat: Add Swagger UI support to OpenAPI Reference Plugin with improved API naming~~ feat(openapi): Add Swagger UI support to OpenAPI Reference Plugin Aug 21, 2025

dinwwwh merged commit 4f28b69 into main Aug 22, 2025
11 checks passed

dosubot Bot mentioned this pull request Sep 11, 2025

OpenAPI Specification Server URLs in SwaggerUI deployed in Docker (Google Cloud Run) #989

Closed

1 task

dinwwwh deleted the copilot/fix-903 branch June 22, 2026 01:52

Uh oh!

Uh oh!

Conversation

Copilot AI commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes Made

New Configuration Options

Implementation Details

Usage Examples

Documentation Improvements

Backward Compatibility

Testing

Uh oh!

Copilot AI commented Aug 20, 2025

Uh oh!

vercel Bot commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dinwwwh Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

dinwwwh Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

dinwwwh Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

dinwwwh Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

dinwwwh Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

dinwwwh Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot commented Aug 21, 2025

Other AI code review bot(s) detected

Review skipped

Chat

Support

CodeRabbit Commands (Invoked using PR/Issue comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Status, Documentation and Community

Uh oh!

codecov Bot commented Aug 21, 2025

Codecov Report

Uh oh!

pkg-pr-new Bot commented Aug 21, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Aug 20, 2025 •

edited

Loading

vercel Bot commented Aug 20, 2025 •

edited

Loading

CodeRabbit Configuration File (`.coderabbit.yaml`)