@inditextech/swagger-ui-plugin-diff-highlight 0.1.0-SNAPSHOT.16.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,73 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
10
+
11
+ "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
12
+
13
+ "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
14
+
15
+ "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
16
+
17
+ "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
18
+
19
+ "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
20
+
21
+ "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
22
+
23
+ "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
24
+
25
+ "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
26
+
27
+ "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
28
+
29
+ 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
30
+
31
+ 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
32
+
33
+ 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
34
+
35
+ (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
36
+
37
+ (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
38
+
39
+ (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
40
+
41
+ (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
42
+
43
+ You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
44
+
45
+ 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
46
+
47
+ 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
48
+
49
+ 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
50
+
51
+ 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
52
+
53
+ 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
54
+
55
+ END OF TERMS AND CONDITIONS
56
+
57
+ APPENDIX: How to apply the Apache License to your work.
58
+
59
+ To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
60
+
61
+ Copyright [yyyy] [name of copyright owner]
62
+
63
+ Licensed under the Apache License, Version 2.0 (the "License");
64
+ you may not use this file except in compliance with the License.
65
+ You may obtain a copy of the License at
66
+
67
+ http://www.apache.org/licenses/LICENSE-2.0
68
+
69
+ Unless required by applicable law or agreed to in writing, software
70
+ distributed under the License is distributed on an "AS IS" BASIS,
71
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
72
+ See the License for the specific language governing permissions and
73
+ limitations under the License.
package/README.md ADDED
@@ -0,0 +1,310 @@
1
+ <!--
2
+ SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
3
+
4
+ SPDX-License-Identifier: Apache-2.0
5
+ -->
6
+
7
+ ![GitHub License](https://img.shields.io/github/license/InditexTech/swagger-ui-plugin-diff-highlight)
8
+
9
+ # swagger-ui-plugin-diff-highlight
10
+
11
+ A [`swagger-ui-react`](https://www.npmjs.com/package/swagger-ui-react) / Swagger UI plugin that **highlights API changes inline** — added, deleted, and updated operations, parameters, responses, and schema properties are marked directly in the Swagger UI, without leaving the docs.
12
+
13
+ It reads custom `x-diff-*` extensions from the loaded OpenAPI document and renders them as visual diff marks.
14
+
15
+ ![Walkthrough demo](https://github.com/user-attachments/assets/3b193a3b-ad4a-4ae9-abed-75419559ab92)
16
+
17
+ ## Features
18
+
19
+ When an API evolves from one version to the next, it is hard to see _what actually changed_ from a plain Swagger UI page. This plugin annotates the rendered document with diff marks driven by `x-diff-*` extensions:
20
+
21
+ | Status | Appearance |
22
+ | --------- | ----------------------------------------------------------- |
23
+ | `added` | green + bold |
24
+ | `deleted` | red + strikethrough |
25
+ | `updated` | inline `old → new` (old in red strikethrough, new in green) |
26
+
27
+ ## Getting Started
28
+
29
+ ### Installation
30
+
31
+ ```bash
32
+ npm install @inditextech/swagger-ui-plugin-diff-highlight
33
+ ```
34
+
35
+ `react`, `react-dom`, and `swagger-ui-react` are peer dependencies — install them in your app if you haven't already:
36
+
37
+ ```bash
38
+ npm install react react-dom swagger-ui-react
39
+ ```
40
+
41
+ ### Usage
42
+
43
+ Register the plugin and import its stylesheet where you render Swagger UI:
44
+
45
+ ```jsx
46
+ import SwaggerUI from "swagger-ui-react";
47
+ import "swagger-ui-react/swagger-ui.css";
48
+
49
+ import DiffHighlightPlugin from "@inditextech/swagger-ui-plugin-diff-highlight";
50
+ import "@inditextech/swagger-ui-plugin-diff-highlight/styles.css";
51
+
52
+ export default function Docs({ spec }) {
53
+ return <SwaggerUI spec={spec} plugins={[DiffHighlightPlugin]} />;
54
+ }
55
+ ```
56
+
57
+ Then feed it an annotated spec. Anything without an annotation renders normally.
58
+
59
+ > The `plugins` prop is read only when Swagger UI mounts. If you toggle the
60
+ > plugin on/off at runtime, change the component `key` to force a remount —
61
+ > see the demo in [`example/`](./example).
62
+
63
+ #### Annotating your OpenAPI document
64
+
65
+ Annotate any operation, parameter, response, or schema property with `x-diff-status`:
66
+
67
+ ```jsonc
68
+ // An added parameter
69
+ {
70
+ "name": "offset",
71
+ "in": "query",
72
+ "schema": { "type": "integer", "default": 0 },
73
+ "x-diff-status": "added"
74
+ }
75
+
76
+ // A deleted parameter
77
+ {
78
+ "name": "sort",
79
+ "in": "query",
80
+ "schema": { "type": "string" },
81
+ "x-diff-status": "deleted"
82
+ }
83
+
84
+ // An added response
85
+ "404": {
86
+ "description": "User not found.",
87
+ "x-diff-status": "added",
88
+ "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
89
+ }
90
+ ```
91
+
92
+ For an **updated** schema property, also provide the before/after sub-schemas so the plugin can render `old → new`:
93
+
94
+ ```jsonc
95
+ "timeout": {
96
+ "type": "integer",
97
+ "x-diff-status": "updated",
98
+ "x-diff-original": { "type": "string" },
99
+ "x-diff-new": { "type": "integer" }
100
+ }
101
+ ```
102
+
103
+ Valid `x-diff-status` values: `added`, `deleted`, `updated`, `unchanged` (or simply omit the extension for unchanged elements).
104
+
105
+ ##### Where each key goes
106
+
107
+ | Extension | Where it lives | Notes |
108
+ | ----------------- | ---------------------------------------------------------------------------- | ------------------------------------------------ |
109
+ | `x-diff-status` | On an operation, a parameter object, a response object, or a schema property | Required on every element you want to mark |
110
+ | `x-diff-original` | On a schema property only | Only with `"updated"`; the **before** sub-schema |
111
+ | `x-diff-new` | On a schema property only | Only with `"updated"`; the **after** sub-schema |
112
+
113
+ All three keys are **sibling properties** of the element they annotate. `x-diff-original` / `x-diff-new` are only read for `"updated"` schema properties — for added/deleted elements, `x-diff-status` alone is enough.
114
+
115
+ #### Generating the annotations automatically
116
+
117
+ You don't have to annotate by hand. Compute the diff between your **old** and **new** OpenAPI documents with any API-diff tool, then merge the result back into your **new** spec as `x-diff-*` extensions before passing it to Swagger UI. The plugin only cares that the final document carries `x-diff-status` on the changed elements — it doesn't care which tool produced the diff.
118
+
119
+ Whatever tool you use, the change types map onto `x-diff-status` the same way:
120
+
121
+ | Diff-tool change type | `x-diff-status` | Extra keys |
122
+ | --------------------------- | --------------- | --------------------------------------------------- |
123
+ | added / new | `added` | – |
124
+ | removed / deleted / missing | `deleted` | – |
125
+ | changed / modified | `updated` | `x-diff-original`, `x-diff-new` (schema properties) |
126
+
127
+ The three examples below convert real output from popular tools into the same annotated spec.
128
+
129
+ ##### Example 1: [`oasdiff`](https://github.com/oasdiff/oasdiff) (YAML)
130
+
131
+ `oasdiff diff old.yaml new.yaml` prints a path-hierarchy diff. Here an operation was added and a query parameter was removed:
132
+
133
+ ```yaml
134
+ paths:
135
+ modified:
136
+ /users:
137
+ operations:
138
+ added:
139
+ - POST
140
+ modified:
141
+ GET:
142
+ parameters:
143
+ deleted:
144
+ query:
145
+ - sort
146
+ ```
147
+
148
+ Apply the mapping to your **new** spec — `added` operation → `x-diff-status: "added"`, `deleted` parameter (re-added so it still renders) → `x-diff-status: "deleted"`:
149
+
150
+ ```jsonc
151
+ "/users": {
152
+ "post": {
153
+ "summary": "Create a user",
154
+ "x-diff-status": "added"
155
+ },
156
+ "get": {
157
+ "parameters": [
158
+ {
159
+ "name": "sort",
160
+ "in": "query",
161
+ "schema": { "type": "string" },
162
+ "x-diff-status": "deleted"
163
+ }
164
+ ]
165
+ }
166
+ }
167
+ ```
168
+
169
+ ##### Example 2: [`openapi-diff`](https://github.com/OpenAPITools/openapi-diff) (JSON)
170
+
171
+ `openapi-diff old.yaml new.yaml --json out.json` emits a structured report with `newEndpoints`, `missingEndpoints`, and `changedOperations`. Here a new endpoint appears and a body property changed type:
172
+
173
+ ```jsonc
174
+ {
175
+ "newEndpoints": [
176
+ { "method": "POST", "pathUrl": "/users", "summary": "Create a user" },
177
+ ],
178
+ "changedOperations": [
179
+ {
180
+ "httpMethod": "GET",
181
+ "pathUrl": "/users/{id}",
182
+ "responseChanged": {
183
+ "changedProperties": {
184
+ "timeout": { "oldType": "string", "newType": "integer" },
185
+ },
186
+ },
187
+ },
188
+ ],
189
+ }
190
+ ```
191
+
192
+ Mark the new operation as `added`, and the changed property as `updated` with its before/after sub-schemas:
193
+
194
+ ```jsonc
195
+ "/users": {
196
+ "post": { "summary": "Create a user", "x-diff-status": "added" }
197
+ }
198
+
199
+ // ...inside the response schema for GET /users/{id}
200
+ "timeout": {
201
+ "type": "integer",
202
+ "x-diff-status": "updated",
203
+ "x-diff-original": { "type": "string" },
204
+ "x-diff-new": { "type": "integer" }
205
+ }
206
+ ```
207
+
208
+ ##### Example 3: [`bump diff`](https://github.com/bump-sh/cli) (Bump.sh, text)
209
+
210
+ Bump.sh's CLI prints a human-readable changelog (run `bump diff old.yaml new.yaml`). It flags breaking changes but isn't machine-structured, so you translate it by eye (or use `bump diff --format markdown`/`json`):
211
+
212
+ ```text
213
+ Modified: GET /users/{id}
214
+ Response modified: 200
215
+ [Breaking] Body attribute modified: timeout
216
+ ```
217
+
218
+ A modified attribute type maps to an `updated` schema property. Supply the old and new types as sub-schemas:
219
+
220
+ ```jsonc
221
+ "timeout": {
222
+ "type": "integer",
223
+ "x-diff-status": "updated",
224
+ "x-diff-original": { "type": "string" },
225
+ "x-diff-new": { "type": "integer" }
226
+ }
227
+ ```
228
+
229
+ > The merge step (folding the diff back into the new spec) is up to you — do it by hand for small diffs, or script it for larger ones. The plugin's only requirement is that the final document carries `x-diff-status` on the changed elements.
230
+
231
+ ## How it works
232
+
233
+ The plugin uses Swagger UI's [`wrapComponents`](https://swagger-ui.github.io/swagger-ui/usage/customization/plugin-api/) API to intercept rendering and attach diff CSS classes. It wraps four components (note the exact registration casing):
234
+
235
+ | Component | What it marks | Where it reads the status |
236
+ | -------------- | ----------------------- | ------------------------------------------------------ |
237
+ | `operation` | An endpoint / opblock | The **unresolved** spec via `specSelectors`/`specPath` |
238
+ | `parameterRow` | A request parameter row | `props.param` / `props.rawParam` |
239
+ | `response` | A response row | `props.response` |
240
+ | `Model` | A schema property | `props.schema` |
241
+
242
+ Two implementation details worth knowing:
243
+
244
+ - **Operations are read from the unresolved spec.** Swagger UI resolves an operation's subtree _lazily_, only once it is expanded. The plugin reads `x-diff-status` straight from `specSelectors.specJson()` using the `specPath`, so the mark is visible whether the operation is **collapsed or expanded**.
245
+ - **Table layout is preserved.** Rows (`<tr>`) must stay direct children of their table, so the plugin wraps them in a `display: contents` element to apply the diff class without breaking the table flow.
246
+
247
+ ### Notes / caveats
248
+
249
+ - Use OpenAPI **3.0.x** documents — the `Model` wrapping relies on the 3.0 render pipeline.
250
+ - Component registration names are case-sensitive: `operation`, `parameterRow` (camelCase), `response` (lowercase), `Model`.
251
+
252
+ ## Demo
253
+
254
+ A full Vite demo lives in [`example/`](./example). It wires a toolbar (toggle inline diffs, open a Changes Report modal) around Swagger UI and the plugin.
255
+
256
+ ```bash
257
+ # 1. build the library from the repo root
258
+ npm install
259
+ npm run build
260
+
261
+ # 2. run the demo
262
+ cd example
263
+ npm install # resolves the library via "file:.."
264
+ npm start # http://localhost:3000
265
+ ```
266
+
267
+ ## Contributing
268
+
269
+ We welcome contributions!
270
+
271
+ Please read our [CONTRIBUTING.md](./CONTRIBUTING.md) and follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
272
+
273
+ ## Acknowledgments
274
+
275
+ - Built on top of [Swagger UI](https://github.com/swagger-api/swagger-ui) and [`swagger-ui-react`](https://www.npmjs.com/package/swagger-ui-react), whose [`wrapComponents`](https://swagger-ui.github.io/swagger-ui/usage/customization/plugin-api/) plugin API makes this plugin possible.
276
+ - Interoperable with popular API-diff tools such as [`oasdiff`](https://github.com/oasdiff/oasdiff), [`openapi-diff`](https://github.com/OpenAPITools/openapi-diff), and [`bump diff`](https://github.com/bump-sh/cli).
277
+
278
+ ## License
279
+
280
+ This project is licensed under the [Apache-2.0 License](./LICENSE).
281
+
282
+ © 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
283
+
284
+ <details>
285
+ <summary>Third-party dependency licenses</summary>
286
+
287
+ Some dependencies are distributed under dual/alternative licenses (`OR`). The license elected for use in this project is listed below:
288
+
289
+ | Dependency | Version | Available Licenses | Elected License |
290
+ | ----------- | ------- | --------------------- | ------------------------------------------------- |
291
+ | `dompurify` | 3.4.12 | Apache-2.0 OR MPL-2.0 | [Apache-2.0](THIRD-PARTY-LICENSES/Apache-2.0.txt) |
292
+ | `type-fest` | 0.20.2 | CC0-1.0 OR MIT | [MIT](THIRD-PARTY-LICENSES/MIT.txt) |
293
+
294
+ Full third-party license texts are available under the [`THIRD-PARTY-LICENSES/`](THIRD-PARTY-LICENSES/) directory:
295
+
296
+ - [0BSD](THIRD-PARTY-LICENSES/0BSD.txt)
297
+ - [Apache-2.0](THIRD-PARTY-LICENSES/Apache-2.0.txt)
298
+ - [BSD-2-Clause](THIRD-PARTY-LICENSES/BSD-2-Clause.txt)
299
+ - [BSD-3-Clause](THIRD-PARTY-LICENSES/BSD-3-Clause.txt)
300
+ - [BlueOak-1.0.0](THIRD-PARTY-LICENSES/BlueOak-1.0.0.txt)
301
+ - [CC-BY-4.0](THIRD-PARTY-LICENSES/CC-BY-4.0.txt)
302
+ - [CC0-1.0](THIRD-PARTY-LICENSES/CC0-1.0.txt)
303
+ - [ISC](THIRD-PARTY-LICENSES/ISC.txt)
304
+ - [MIT](THIRD-PARTY-LICENSES/MIT.txt)
305
+ - [MIT-0](THIRD-PARTY-LICENSES/MIT-0.txt)
306
+ - [MPL-2.0](THIRD-PARTY-LICENSES/MPL-2.0.txt)
307
+ - [Python-2.0](THIRD-PARTY-LICENSES/Python-2.0.txt)
308
+ - [Unlicense](THIRD-PARTY-LICENSES/Unlicense.txt)
309
+
310
+ </details>
package/dist/diff.css ADDED
@@ -0,0 +1,83 @@
1
+ /* SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.) */
2
+ /* SPDX-License-Identifier: Apache-2.0 */
3
+
4
+ /* ----------------------------------------------------------------------------
5
+ * Diff highlighting
6
+ * ------------------------------------------------------------------------- */
7
+
8
+ /* Added: green + bold */
9
+ .diff-added,
10
+ .diff-added * {
11
+ color: #1b7e3c !important;
12
+ font-weight: 700 !important;
13
+ }
14
+
15
+ /* Deleted: red + strikethrough */
16
+ .diff-deleted,
17
+ .diff-deleted * {
18
+ color: #c0392b !important;
19
+ text-decoration: line-through !important;
20
+ }
21
+
22
+ /* Updated rows (parameters / operations / responses): amber marker */
23
+ .diff-wrap.diff-updated * {
24
+ color: #b9770e !important;
25
+ }
26
+
27
+ /* Updated attribute value: original (red strike) -> new (green bold) */
28
+ .diff-updated-inline {
29
+ display: inline-flex;
30
+ align-items: center;
31
+ gap: 4px;
32
+ }
33
+
34
+ .diff-updated-old {
35
+ color: #c0392b;
36
+ text-decoration: line-through;
37
+ font-weight: 600;
38
+ }
39
+
40
+ .diff-updated-new {
41
+ color: #1b7e3c;
42
+ font-weight: 700;
43
+ }
44
+
45
+ .diff-updated-arrow {
46
+ color: #6b6b6b;
47
+ }
48
+
49
+ /* Mark the schema property NAME cell, not just its value.
50
+ * The value cell (2nd <td>) carries the diff class; :has() lets us reach the
51
+ * sibling name cell (1st <td>) rendered by ObjectModel. The `> td >` scoping
52
+ * keeps a change from leaking onto ancestor rows of nested objects. */
53
+ .swagger-ui tr.property-row:has(> td > .diff-deleted) > td:first-child,
54
+ .swagger-ui tr.property-row:has(> td > .diff-deleted) > td:first-child * {
55
+ color: #c0392b !important;
56
+ text-decoration: line-through !important;
57
+ }
58
+
59
+ .swagger-ui tr.property-row:has(> td > .diff-added) > td:first-child,
60
+ .swagger-ui tr.property-row:has(> td > .diff-added) > td:first-child * {
61
+ color: #1b7e3c !important;
62
+ font-weight: 700 !important;
63
+ }
64
+
65
+ /* Operation-level changes: tag the whole opblock but only paint the
66
+ * always-visible summary row, so the mark is shown whether the operation is
67
+ * collapsed or expanded. */
68
+ .diff-op-deleted .opblock-summary,
69
+ .diff-op-deleted .opblock-summary * {
70
+ color: #c0392b !important;
71
+ text-decoration: line-through !important;
72
+ }
73
+
74
+ .diff-op-added .opblock-summary,
75
+ .diff-op-added .opblock-summary * {
76
+ color: #1b7e3c !important;
77
+ font-weight: 700 !important;
78
+ }
79
+
80
+ .diff-op-updated .opblock-summary,
81
+ .diff-op-updated .opblock-summary * {
82
+ color: #b9770e !important;
83
+ }
package/dist/index.js ADDED
@@ -0,0 +1,132 @@
1
+ var __create = Object.create;
2
+ var __defProp = Object.defineProperty;
3
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
+ var __getOwnPropNames = Object.getOwnPropertyNames;
5
+ var __getProtoOf = Object.getPrototypeOf;
6
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
7
+ var __export = (target, all) => {
8
+ for (var name in all)
9
+ __defProp(target, name, { get: all[name], enumerable: true });
10
+ };
11
+ var __copyProps = (to, from, except, desc) => {
12
+ if (from && typeof from === "object" || typeof from === "function") {
13
+ for (let key of __getOwnPropNames(from))
14
+ if (!__hasOwnProp.call(to, key) && key !== except)
15
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
16
+ }
17
+ return to;
18
+ };
19
+ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
20
+ // If the importer is in node compatibility mode or this is not an ESM
21
+ // file that has been converted to a CommonJS file using a Babel-
22
+ // compatible transform (i.e. "__esModule" has not been set), then set
23
+ // "default" to the CommonJS "module.exports" for node compatibility.
24
+ isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
25
+ mod
26
+ ));
27
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
28
+
29
+ // src/index.js
30
+ var index_exports = {};
31
+ __export(index_exports, {
32
+ DiffHighlightPlugin: () => DiffHighlightPlugin_default,
33
+ default: () => DiffHighlightPlugin_default
34
+ });
35
+ module.exports = __toCommonJS(index_exports);
36
+
37
+ // src/DiffHighlightPlugin.jsx
38
+ var import_react = __toESM(require("react"));
39
+ var wrapContents = (status, children) => /* @__PURE__ */ import_react.default.createElement("div", { className: `diff-wrap diff-${status}`, style: { display: "contents" } }, children);
40
+ var readStatus = (immutableMap) => immutableMap && typeof immutableMap.get === "function" ? immutableMap.get("x-diff-status") : void 0;
41
+ var describeSchema = (schema) => {
42
+ if (!schema || typeof schema.get !== "function") {
43
+ return "any";
44
+ }
45
+ const type = schema.get("type");
46
+ const format = schema.get("format");
47
+ if (!type) {
48
+ return "object";
49
+ }
50
+ return format ? `${type}($${format})` : type;
51
+ };
52
+ var DiffHighlightPlugin = () => ({
53
+ wrapComponents: {
54
+ /**
55
+ * Schema properties: each property value is rendered as a nested `<Model>`.
56
+ */
57
+ Model: (Original) => (props) => {
58
+ const status = readStatus(props.schema);
59
+ if (status === "deleted") {
60
+ return /* @__PURE__ */ import_react.default.createElement("span", { className: "diff-deleted" }, /* @__PURE__ */ import_react.default.createElement(Original, { ...props }));
61
+ }
62
+ if (status === "added") {
63
+ return /* @__PURE__ */ import_react.default.createElement("span", { className: "diff-added" }, /* @__PURE__ */ import_react.default.createElement(Original, { ...props }));
64
+ }
65
+ if (status === "updated") {
66
+ const original = props.schema.get("x-diff-original");
67
+ const updated = props.schema.get("x-diff-new");
68
+ return /* @__PURE__ */ import_react.default.createElement("span", { className: "diff-updated-inline" }, /* @__PURE__ */ import_react.default.createElement("span", { className: "diff-updated-old" }, describeSchema(original)), /* @__PURE__ */ import_react.default.createElement("span", { className: "diff-updated-arrow" }, " \u2192 "), /* @__PURE__ */ import_react.default.createElement("span", { className: "diff-updated-new" }, describeSchema(updated)));
69
+ }
70
+ return /* @__PURE__ */ import_react.default.createElement(Original, { ...props });
71
+ },
72
+ /**
73
+ * Parameters: one `<tr>` per parameter; status lives on the param object.
74
+ * Registered name is camelCase "parameterRow".
75
+ */
76
+ parameterRow: (Original) => (props) => {
77
+ const status = readStatus(props.param || props.rawParam);
78
+ if (status && status !== "unchanged") {
79
+ return wrapContents(status, /* @__PURE__ */ import_react.default.createElement(Original, { ...props }));
80
+ }
81
+ return /* @__PURE__ */ import_react.default.createElement(Original, { ...props });
82
+ },
83
+ /**
84
+ * Operations: the status must be read from the *unresolved* spec.
85
+ *
86
+ * swagger-ui resolves an operation's subtree lazily, only once it is
87
+ * expanded. Until then `operationProps.get("op")` is an empty Map, so a
88
+ * wrapper on `OperationSummary` would only see the diff status while the
89
+ * operation is open. Wrapping `operation` instead gives us `specSelectors`
90
+ * + `specPath`, letting us read `x-diff-status` straight from the loaded
91
+ * document — available whether the operation is collapsed or expanded.
92
+ *
93
+ * The wrapper tags the whole opblock; CSS scopes the highlight to the
94
+ * always-visible `.opblock-summary` so the mark shows in both states.
95
+ */
96
+ operation: (Original) => (props) => {
97
+ const { specSelectors, specPath } = props;
98
+ let status;
99
+ if (specSelectors && typeof specSelectors.specJson === "function" && specPath && typeof specPath.toJS === "function") {
100
+ const op = specSelectors.specJson().getIn(specPath.toJS());
101
+ status = readStatus(op);
102
+ }
103
+ if (status && status !== "unchanged") {
104
+ return /* @__PURE__ */ import_react.default.createElement(
105
+ "div",
106
+ {
107
+ className: `diff-op diff-op-${status}`,
108
+ style: { display: "contents" }
109
+ },
110
+ /* @__PURE__ */ import_react.default.createElement(Original, { ...props })
111
+ );
112
+ }
113
+ return /* @__PURE__ */ import_react.default.createElement(Original, { ...props });
114
+ },
115
+ /**
116
+ * Responses: one `<tr>` per status code; status lives on the response object.
117
+ * Registered name is lowercase "response".
118
+ */
119
+ response: (Original) => (props) => {
120
+ const status = readStatus(props.response);
121
+ if (status && status !== "unchanged") {
122
+ return wrapContents(status, /* @__PURE__ */ import_react.default.createElement(Original, { ...props }));
123
+ }
124
+ return /* @__PURE__ */ import_react.default.createElement(Original, { ...props });
125
+ }
126
+ }
127
+ });
128
+ var DiffHighlightPlugin_default = DiffHighlightPlugin;
129
+ // Annotate the CommonJS export names for ESM import in node:
130
+ 0 && (module.exports = {
131
+ DiffHighlightPlugin
132
+ });
package/dist/index.mjs ADDED
@@ -0,0 +1,96 @@
1
+ // src/DiffHighlightPlugin.jsx
2
+ import React from "react";
3
+ var wrapContents = (status, children) => /* @__PURE__ */ React.createElement("div", { className: `diff-wrap diff-${status}`, style: { display: "contents" } }, children);
4
+ var readStatus = (immutableMap) => immutableMap && typeof immutableMap.get === "function" ? immutableMap.get("x-diff-status") : void 0;
5
+ var describeSchema = (schema) => {
6
+ if (!schema || typeof schema.get !== "function") {
7
+ return "any";
8
+ }
9
+ const type = schema.get("type");
10
+ const format = schema.get("format");
11
+ if (!type) {
12
+ return "object";
13
+ }
14
+ return format ? `${type}($${format})` : type;
15
+ };
16
+ var DiffHighlightPlugin = () => ({
17
+ wrapComponents: {
18
+ /**
19
+ * Schema properties: each property value is rendered as a nested `<Model>`.
20
+ */
21
+ Model: (Original) => (props) => {
22
+ const status = readStatus(props.schema);
23
+ if (status === "deleted") {
24
+ return /* @__PURE__ */ React.createElement("span", { className: "diff-deleted" }, /* @__PURE__ */ React.createElement(Original, { ...props }));
25
+ }
26
+ if (status === "added") {
27
+ return /* @__PURE__ */ React.createElement("span", { className: "diff-added" }, /* @__PURE__ */ React.createElement(Original, { ...props }));
28
+ }
29
+ if (status === "updated") {
30
+ const original = props.schema.get("x-diff-original");
31
+ const updated = props.schema.get("x-diff-new");
32
+ return /* @__PURE__ */ React.createElement("span", { className: "diff-updated-inline" }, /* @__PURE__ */ React.createElement("span", { className: "diff-updated-old" }, describeSchema(original)), /* @__PURE__ */ React.createElement("span", { className: "diff-updated-arrow" }, " \u2192 "), /* @__PURE__ */ React.createElement("span", { className: "diff-updated-new" }, describeSchema(updated)));
33
+ }
34
+ return /* @__PURE__ */ React.createElement(Original, { ...props });
35
+ },
36
+ /**
37
+ * Parameters: one `<tr>` per parameter; status lives on the param object.
38
+ * Registered name is camelCase "parameterRow".
39
+ */
40
+ parameterRow: (Original) => (props) => {
41
+ const status = readStatus(props.param || props.rawParam);
42
+ if (status && status !== "unchanged") {
43
+ return wrapContents(status, /* @__PURE__ */ React.createElement(Original, { ...props }));
44
+ }
45
+ return /* @__PURE__ */ React.createElement(Original, { ...props });
46
+ },
47
+ /**
48
+ * Operations: the status must be read from the *unresolved* spec.
49
+ *
50
+ * swagger-ui resolves an operation's subtree lazily, only once it is
51
+ * expanded. Until then `operationProps.get("op")` is an empty Map, so a
52
+ * wrapper on `OperationSummary` would only see the diff status while the
53
+ * operation is open. Wrapping `operation` instead gives us `specSelectors`
54
+ * + `specPath`, letting us read `x-diff-status` straight from the loaded
55
+ * document — available whether the operation is collapsed or expanded.
56
+ *
57
+ * The wrapper tags the whole opblock; CSS scopes the highlight to the
58
+ * always-visible `.opblock-summary` so the mark shows in both states.
59
+ */
60
+ operation: (Original) => (props) => {
61
+ const { specSelectors, specPath } = props;
62
+ let status;
63
+ if (specSelectors && typeof specSelectors.specJson === "function" && specPath && typeof specPath.toJS === "function") {
64
+ const op = specSelectors.specJson().getIn(specPath.toJS());
65
+ status = readStatus(op);
66
+ }
67
+ if (status && status !== "unchanged") {
68
+ return /* @__PURE__ */ React.createElement(
69
+ "div",
70
+ {
71
+ className: `diff-op diff-op-${status}`,
72
+ style: { display: "contents" }
73
+ },
74
+ /* @__PURE__ */ React.createElement(Original, { ...props })
75
+ );
76
+ }
77
+ return /* @__PURE__ */ React.createElement(Original, { ...props });
78
+ },
79
+ /**
80
+ * Responses: one `<tr>` per status code; status lives on the response object.
81
+ * Registered name is lowercase "response".
82
+ */
83
+ response: (Original) => (props) => {
84
+ const status = readStatus(props.response);
85
+ if (status && status !== "unchanged") {
86
+ return wrapContents(status, /* @__PURE__ */ React.createElement(Original, { ...props }));
87
+ }
88
+ return /* @__PURE__ */ React.createElement(Original, { ...props });
89
+ }
90
+ }
91
+ });
92
+ var DiffHighlightPlugin_default = DiffHighlightPlugin;
93
+ export {
94
+ DiffHighlightPlugin_default as DiffHighlightPlugin,
95
+ DiffHighlightPlugin_default as default
96
+ };
package/package.json ADDED
@@ -0,0 +1,102 @@
1
+ {
2
+ "name": "@inditextech/swagger-ui-plugin-diff-highlight",
3
+ "version": "0.1.0-SNAPSHOT.16.1",
4
+ "description": "Highlight API changes (added/updated/deleted) inline in swagger-ui-react via a custom diff-highlighting plugin.",
5
+ "keywords": [
6
+ "swagger",
7
+ "swagger-ui",
8
+ "swagger-ui-react",
9
+ "swagger-ui-plugin",
10
+ "openapi",
11
+ "openapi-diff",
12
+ "oas",
13
+ "oasdiff",
14
+ "api",
15
+ "api-diff",
16
+ "api-changes",
17
+ "api-versioning",
18
+ "api-documentation",
19
+ "diff",
20
+ "diff-highlight",
21
+ "diff-viewer",
22
+ "change-highlight",
23
+ "changelog",
24
+ "rest",
25
+ "react",
26
+ "plugin",
27
+ "highlight"
28
+ ],
29
+ "license": "Apache-2.0",
30
+ "author": "Bruno Pedro <brunolgp@inditex.com>",
31
+ "homepage": "https://github.com/InditexTech/swagger-ui-plugin-diff-highlight#readme",
32
+ "repository": {
33
+ "type": "git",
34
+ "url": "git+https://github.com/InditexTech/swagger-ui-plugin-diff-highlight.git"
35
+ },
36
+ "bugs": {
37
+ "url": "https://github.com/InditexTech/swagger-ui-plugin-diff-highlight/issues"
38
+ },
39
+ "main": "./dist/index.js",
40
+ "module": "./dist/index.mjs",
41
+ "types": "./types/index.d.ts",
42
+ "exports": {
43
+ ".": {
44
+ "types": "./types/index.d.ts",
45
+ "import": "./dist/index.mjs",
46
+ "require": "./dist/index.js"
47
+ },
48
+ "./styles.css": "./dist/diff.css"
49
+ },
50
+ "sideEffects": [
51
+ "*.css"
52
+ ],
53
+ "files": [
54
+ "dist",
55
+ "types"
56
+ ],
57
+ "scripts": {
58
+ "build": "tsup",
59
+ "test": "vitest run",
60
+ "test:watch": "vitest",
61
+ "lint": "eslint .",
62
+ "lint:fix": "eslint . --fix",
63
+ "format": "prettier --write .",
64
+ "format:check": "prettier --check .",
65
+ "verify": "npm run lint && npm run format:check && npm run test && npm run build",
66
+ "prepublishOnly": "npm run lint && npm run format:check && npm test && npm run build"
67
+ },
68
+ "peerDependencies": {
69
+ "react": ">=17",
70
+ "react-dom": ">=17",
71
+ "swagger-ui-react": ">=4"
72
+ },
73
+ "devDependencies": {
74
+ "@eslint/js": "^9.39.4",
75
+ "@testing-library/jest-dom": "^6.6.3",
76
+ "@testing-library/react": "^16.1.0",
77
+ "eslint": "^9.39.4",
78
+ "eslint-config-prettier": "^10.1.8",
79
+ "eslint-plugin-react": "^7.37.5",
80
+ "eslint-plugin-react-hooks": "^7.1.1",
81
+ "globals": "^17.7.0",
82
+ "immutable": "^4.3.9",
83
+ "jsdom": "^29.1.1",
84
+ "prettier": "^3.9.4",
85
+ "react": "^18.3.1",
86
+ "react-dom": "^18.3.1",
87
+ "swagger-ui-react": "^5.32.14",
88
+ "tsup": "^8.3.5",
89
+ "typescript-eslint": "^8.62.1",
90
+ "vitest": "^4.1.9"
91
+ },
92
+ "overrides": {
93
+ "esbuild": "^0.28.1",
94
+ "js-yaml": "^4.3.2"
95
+ },
96
+ "publishConfig": {
97
+ "access": "public"
98
+ },
99
+ "engines": {
100
+ "node": ">=18"
101
+ }
102
+ }
@@ -0,0 +1,32 @@
1
+ // SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ import type { ComponentType } from "react";
4
+
5
+ /**
6
+ * The partial Swagger UI "system" returned by the plugin: a map of component
7
+ * names to wrappers applied through Swagger UI's `wrapComponents` API.
8
+ */
9
+ export interface DiffHighlightSystem {
10
+ wrapComponents: Record<
11
+ string,
12
+ (Original: ComponentType<any>, system: unknown) => ComponentType<any>
13
+ >;
14
+ }
15
+
16
+ /**
17
+ * A swagger-ui-react / Swagger UI plugin that highlights API changes inline,
18
+ * based on `x-diff-*` extensions present in the loaded OpenAPI document
19
+ * (`added`, `deleted`, `updated`).
20
+ *
21
+ * @example
22
+ * import SwaggerUI from "swagger-ui-react";
23
+ * import "swagger-ui-react/swagger-ui.css";
24
+ * import DiffHighlightPlugin from "@inditextech/swagger-ui-plugin-diff-highlight";
25
+ * import "@inditextech/swagger-ui-plugin-diff-highlight/styles.css";
26
+ *
27
+ * <SwaggerUI spec={spec} plugins={[DiffHighlightPlugin]} />;
28
+ */
29
+ declare const DiffHighlightPlugin: () => DiffHighlightSystem;
30
+
31
+ export default DiffHighlightPlugin;
32
+ export { DiffHighlightPlugin };