-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathabout.html
More file actions
329 lines (317 loc) · 23.7 KB
/
Copy pathabout.html
File metadata and controls
329 lines (317 loc) · 23.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
<title>About - Cisco IOS XE OpenAPI Documentation Hub</title>
<meta http-equiv="X-Content-Type-Options" content="nosniff">
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' https://*.clarity.ms https://*.posthog.com https://*.i.posthog.com; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' https://*.clarity.ms https://*.posthog.com https://*.i.posthog.com;">
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: 'Roboto', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif; background: #f5f5f5; color: #333; line-height: 1.6; }
.header { background: linear-gradient(135deg, #1565C0 0%, #0D47A1 100%); color: white; padding: 40px 20px; }
.container { max-width: 1200px; margin: 0 auto; }
.header h1 { font-size: 2.4rem; margin-bottom: 8px; }
.header .meta { opacity: 0.9; font-size: 1.05rem; }
.back-link { display: inline-block; background: white; color: #1565C0; padding: 8px 16px; border-radius: 4px; text-decoration: none; margin-top: 20px; font-weight: 500; }
.back-link:hover { background: #E3F2FD; }
.content { max-width: 1200px; margin: 0 auto; padding: 32px 20px 16px; }
.section { background: white; border-radius: 8px; padding: 28px; margin-bottom: 24px; box-shadow: 0 2px 8px rgba(0,0,0,0.08); }
.section h2 { color: #1565C0; margin-bottom: 14px; font-size: 1.5rem; }
.section h3 { color: #0D47A1; margin: 18px 0 10px; font-size: 1.15rem; }
.section p { margin-bottom: 12px; color: #444; }
.section ul { margin: 8px 0 12px 22px; }
.section li { margin-bottom: 6px; color: #444; }
.section a { color: #1565C0; text-decoration: none; border-bottom: 1px dotted #1565C0; }
.section a:hover { border-bottom-style: solid; }
.stat-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 14px; margin: 16px 0; }
.stat-card { background: #E3F2FD; border-left: 4px solid #1565C0; padding: 14px 16px; border-radius: 4px; }
.stat-value { font-size: 1.8rem; font-weight: 700; color: #1565C0; line-height: 1.1; }
.stat-label { color: #555; font-size: 0.85rem; margin-top: 4px; }
.feature-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 16px; margin: 14px 0; }
.feature { background: #F8F9FB; border: 1px solid #E3E7EE; border-radius: 6px; padding: 16px; }
.feature h4 { color: #1565C0; margin-bottom: 6px; font-size: 1rem; }
.feature p { font-size: 0.9rem; color: #555; margin: 0; }
.pill { display: inline-block; padding: 2px 10px; border-radius: 10px; font-size: 0.78rem; font-weight: 500; background: #E3F2FD; color: #1565C0; margin: 2px 4px 2px 0; }
.cta-row { display: flex; flex-wrap: wrap; gap: 12px; margin-top: 18px; }
.cta { display: inline-block; padding: 10px 18px; border-radius: 6px; text-decoration: none; font-weight: 500; font-size: 0.95rem; transition: opacity 0.15s, transform 0.1s; }
.cta:hover { opacity: 0.9; transform: translateY(-1px); }
.cta-primary { background: #1565C0; color: white !important; border-bottom: none !important; }
.cta-secondary { background: white; color: #1565C0 !important; border: 1px solid #1565C0; border-bottom: 1px solid #1565C0 !important; }
.cta-ghost { background: transparent; color: #1565C0 !important; border: 1px solid #BBDEFB; border-bottom: 1px solid #BBDEFB !important; }
code { background: #F1F3F6; padding: 2px 6px; border-radius: 3px; font-family: 'Consolas', 'Monaco', monospace; font-size: 0.88em; color: #B71C1C; }
.release-table { width: 100%; border-collapse: collapse; margin-top: 10px; }
.release-table th, .release-table td { padding: 8px 12px; border-bottom: 1px solid #E3E7EE; text-align: left; font-size: 0.9rem; }
.release-table th { background: #F8F9FB; color: #1565C0; font-weight: 500; }
.quote { border-left: 4px solid #1565C0; padding: 10px 16px; margin: 12px 0; background: #F8F9FB; color: #444; font-style: italic; }
@media (max-width: 640px) {
.header h1 { font-size: 1.9rem; }
.section { padding: 20px; }
}
</style>
<link rel="stylesheet" href="assets/css/site.css">
<link rel="stylesheet" href="assets/css/components.css">
<script src="assets/js/site-chrome.js" defer></script>
<!-- BEGIN seo-meta (managed by scripts/inject_seo_meta.py) -->
<meta name="description" content="About the Cisco IOS XE OpenAPI Documentation Hub: project mission, technical capabilities, releases covered, and how to give feedback or contribute.">
<meta name="keywords" content="Cisco IOS XE, YANG, OpenAPI, RESTCONF, NETCONF, network automation, model-driven telemetry, programmability, swagger, about, feedback">
<meta name="author" content="Cisco DevNet">
<meta name="theme-color" content="#1565c0" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#0a0d12" media="(prefers-color-scheme: dark)">
<meta name="format-detection" content="telephone=no">
<link rel="canonical" href="https://ciscodevnet.github.io/cisco-ios-xe-openapi-swagger/about.html">
<meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1">
<script type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://ciscodevnet.github.io/cisco-ios-xe-openapi-swagger/"},{"@type":"ListItem","position":2,"name":"About","item":"https://ciscodevnet.github.io/cisco-ios-xe-openapi-swagger/about.html"}]}</script>
<link rel="icon" type="image/svg+xml" href="assets/icons/favicon.svg">
<link rel="alternate icon" type="image/x-icon" href="assets/icons/favicon.ico">
<link rel="apple-touch-icon" sizes="180x180" href="assets/icons/apple-touch-icon.png">
<meta property="og:type" content="website">
<meta property="og:site_name" content="Cisco IOS XE OpenAPI & YANG Docs">
<meta property="og:title" content="About - Cisco IOS XE OpenAPI Documentation Hub">
<meta property="og:description" content="Project mission, technical capabilities, releases covered, and how to engage.">
<meta property="og:url" content="https://ciscodevnet.github.io/cisco-ios-xe-openapi-swagger/about.html">
<meta property="og:image" content="https://ciscodevnet.github.io/cisco-ios-xe-openapi-swagger/assets/icons/og-image.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="About - Cisco IOS XE OpenAPI Documentation Hub">
<meta name="twitter:description" content="Project mission, technical capabilities, releases covered, and how to engage.">
<meta name="twitter:image" content="https://ciscodevnet.github.io/cisco-ios-xe-openapi-swagger/assets/icons/og-image.png">
<!-- END seo-meta -->
<link rel="manifest" href="site.webmanifest">
<!-- Structured data: helps search engines surface the project page with
rich metadata (name, URL, audience, organization). Schema.org WebSite
+ Organization is the simplest combo for a project landing page. -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "WebSite",
"@id": "https://ciscodevnet.github.io/cisco-ios-xe-openapi-swagger/#website",
"url": "https://ciscodevnet.github.io/cisco-ios-xe-openapi-swagger/",
"name": "Cisco IOS XE OpenAPI Documentation Hub",
"description": "Browse, search, compare, and generate code against every YANG model published in Cisco IOS XE releases 17.9 through 26.1.1.",
"inLanguage": "en",
"publisher": { "@id": "https://www.cisco.com/#organization" }
},
{
"@type": "WebPage",
"@id": "https://ciscodevnet.github.io/cisco-ios-xe-openapi-swagger/about.html",
"url": "https://ciscodevnet.github.io/cisco-ios-xe-openapi-swagger/about.html",
"name": "About - Cisco IOS XE OpenAPI Documentation Hub",
"isPartOf": { "@id": "https://ciscodevnet.github.io/cisco-ios-xe-openapi-swagger/#website" },
"audience": {
"@type": "Audience",
"audienceType": "Network engineers, automation developers, DevOps practitioners"
}
},
{
"@type": "Organization",
"@id": "https://www.cisco.com/#organization",
"name": "Cisco DevNet",
"url": "https://developer.cisco.com/"
}
]
}
</script>
<!-- BEGIN pwa (managed by scripts/inject_pwa.py) -->
<link rel="manifest" href="site.webmanifest">
<script src="assets/js/analytics-config.js"></script>
<script src="assets/js/sw-register.js" defer></script>
<script src="assets/js/analytics.js" defer></script>
<!-- END pwa -->
</head>
<body data-anchors="on">
<header class="header">
<div class="container">
<h1>About the IOS XE OpenAPI Documentation Hub</h1>
<p class="meta">A community-driven catalog of Cisco IOS XE RESTCONF, NETCONF, and YANG-Push surface area — rendered as Swagger / OpenAPI 3.0.</p>
<a href="index.html" class="back-link">← Hub</a>
</div>
</header>
<main class="content">
<!-- ==================== MISSION ==================== -->
<section class="section" id="mission" aria-labelledby="mission-h">
<h2 id="mission-h">Why this site exists</h2>
<p>
Cisco IOS XE ships thousands of YANG models that drive RESTCONF, NETCONF, gNMI, and
model-driven telemetry. The official YANG repositories live at
<a href="https://github.com/YangModels/yang" target="_blank" rel="noopener noreferrer">YangModels/yang</a>
and are the source of truth — but they are <em>trees</em>, not interactive
API documentation.
</p>
<p>
This project compiles those models into <strong>OpenAPI 3.0</strong> specifications
you can browse in Swagger UI, search, deep-link to, export to Postman or Bruno, and
use to generate request snippets in Python, curl, JavaScript, and Go. Every spec
ships with a realistic, RFC 7951-compliant example payload — no empty
<code>{}</code> stubs — so you can copy a body and use it against a real device.
</p>
<div class="quote">
The goal is simple: <strong>make the IOS XE programmability surface discoverable and
usable in under five minutes</strong>, regardless of whether you arrive via SNMP-to-YANG
migration, RESTCONF API exploration, telemetry XPath authoring, or model-version
diffing.
</div>
</section>
<!-- ==================== STATS ==================== -->
<section class="section" id="stats" aria-labelledby="stats-h">
<h2 id="stats-h">By the numbers (26.1.1 default)</h2>
<div class="stat-grid">
<div class="stat-card"><div class="stat-value" data-stat-about="specs">988</div><div class="stat-label">OpenAPI 3.0 specifications</div></div>
<div class="stat-card"><div class="stat-value" data-stat-about="paths">82,856</div><div class="stat-label">RESTCONF paths</div></div>
<div class="stat-card"><div class="stat-value" data-stat-about="operations">246,677</div><div class="stat-label">Total API operations</div></div>
<div class="stat-card"><div class="stat-value" data-stat-about="yang_modules">1,319</div><div class="stat-label">YANG modules tracked</div></div>
<div class="stat-card"><div class="stat-value" data-stat-about="yang_tree_files">643</div><div class="stat-label">YANG tree files</div></div>
<div class="stat-card"><div class="stat-value">9</div><div class="stat-label">Model categories</div></div>
<div class="stat-card"><div class="stat-value">5</div><div class="stat-label">IOS XE releases</div></div>
<div class="stat-card"><div class="stat-value">100%</div><div class="stat-label">YANG-module accountability</div></div>
</div>
<p style="font-size:0.85rem;color:#777;">
Live, cross-release counts: see the
<a href="yang-accountability-compare.html">version comparison matrix</a> and the
machine-readable
<a href="version-stats.json">version-stats.json</a>.
</p>
</section>
<!-- ==================== CAPABILITIES ==================== -->
<section class="section" id="capabilities" aria-labelledby="caps-h">
<h2 id="caps-h">What you can do here</h2>
<div class="feature-grid">
<div class="feature">
<h4>Browse interactive Swagger UI</h4>
<p>Nine viewer categories (operational, native config, OpenConfig, IETF, MIB, RPC, events, config, other) each with their own searchable, deep-linkable Swagger UI.</p>
</div>
<div class="feature">
<h4>Generate request snippets</h4>
<p>The <a href="code-generator.html">Code Generator</a> emits Python (requests), curl, JavaScript (fetch), and Go templates for any path — with realistic example bodies pre-filled.</p>
</div>
<div class="feature">
<h4>Diff models across releases</h4>
<p>The <a href="tree-compare.html">tree compare</a> tool shows side-by-side YANG trees with diff highlighting, and the <a href="yang-accountability-compare.html">accountability matrix</a> tracks per-version coverage across 17.9.x → 26.1.1.</p>
</div>
<div class="feature">
<h4>Author MDT telemetry filters</h4>
<p>The <a href="telemetry.html">telemetry builder</a> converts OpenAPI paths into MDT xpath filters ready for YANG-Push subscriptions, with CSV export.</p>
</div>
<div class="feature">
<h4>Export to Postman or Bruno</h4>
<p>Per-category Postman collections (max ~23 MB per shard) and Bruno workspaces are pre-built for every release and downloadable from the <a href="exports.html">Exports</a> page.</p>
</div>
<div class="feature">
<h4>Audit every YANG module</h4>
<p>The <a href="yang-accountability.html">accountability report</a> maps every Cisco-IOS-XE YANG module to its spec, tree, and excluded reason — 100% accountability with CSV export.</p>
</div>
<div class="feature">
<h4>Share permalinks</h4>
<p>Every page deep-links via URL hash (release, search query, filters, module, spec, path). Copy-Share-Link buttons reproduce the exact view a teammate is looking at.</p>
</div>
<div class="feature">
<h4>Use it offline</h4>
<p>Service-worker caching, PWA install, full keyboard navigation (<kbd>?</kbd> for shortcuts), dark mode, and print-optimised stylesheets across every page.</p>
</div>
</div>
</section>
<!-- ==================== RELEASES ==================== -->
<section class="section" id="releases" aria-labelledby="rel-h">
<h2 id="rel-h">Releases covered</h2>
<table class="release-table">
<thead>
<tr><th>Release</th><th>Status</th><th>YangModels path</th><th>YANG modules</th></tr>
</thead>
<tbody>
<tr><td><strong>26.1.1</strong> <span class="pill">default</span></td><td>Active — newest</td><td><code>vendor/cisco/xe/2611</code></td><td>742</td></tr>
<tr><td>17.18.1</td><td>Active</td><td><code>vendor/cisco/xe/17181</code></td><td>715</td></tr>
<tr><td>17.15.x</td><td>Active</td><td><code>vendor/cisco/xe/17151</code></td><td>683</td></tr>
<tr><td>17.12.x</td><td>Active</td><td><code>vendor/cisco/xe/17121</code></td><td>637</td></tr>
<tr><td>17.9.x</td><td>Active — oldest supported</td><td><code>vendor/cisco/xe/1791</code></td><td>620</td></tr>
</tbody>
</table>
<p style="margin-top:14px;font-size:0.9rem;">
The header dropdown picks the active release; every page (Swagger, tree, accountability,
telemetry, code generator) re-fetches data for that release with a single click.
</p>
</section>
<!-- ==================== HOW IT IS BUILT ==================== -->
<section class="section" id="architecture" aria-labelledby="arch-h">
<h2 id="arch-h">How it’s built</h2>
<ul>
<li><strong>Static GitHub Pages site.</strong> No backend, no runtime build, no JavaScript framework. Vanilla JS, served from <code>'self'</code> under a strict CSP (with explicit <code>*.clarity.ms</code> allowlist entries for analytics). Core JS libraries are vendored locally; only Microsoft Clarity telemetry egresses outbound. See <a href="docs/SELF_HOSTING.md">SELF_HOSTING.md</a>.</li>
<li><strong>Python generators</strong> (<code>generators/*.py</code>) walk resolved YANG trees and emit OpenAPI 3.0 specs — one generator per model type (oper, native, openconfig, ietf, mib, rpc, events, cfg, other).</li>
<li><strong>Realistic example payloads</strong> are injected by <code>scripts/enrich_v2_specs.py</code> for every POST / PUT / PATCH body using RFC 7951 JSON encoding.</li>
<li><strong>Live-device validation.</strong> <code>scripts/validate_examples_c9kv.py</code> exercises the generated examples against a real Catalyst 9000V (or any IOS XE 17.18.1+ device).</li>
<li><strong>Schema tests.</strong> 143 unit tests in <code>tests/</code> gate every manifest and every release artifact in CI before merge.</li>
<li><strong>Swagger UI 5.31.0, fuse.js 7.0.0, chart.js 4.4.0</strong> are vendored locally under <code>assets/vendor/</code> with SHA-384 SRI verification — no CDN, no Google Fonts.</li>
</ul>
<p style="margin-top:10px;">
For repo conventions, contributor workflow, and a per-task “what to edit” table see
<a href="CONTRIBUTING.md">CONTRIBUTING.md</a> and
<a href="AGENTS.md">AGENTS.md</a>.
</p>
</section>
<!-- ==================== ENGAGE ==================== -->
<section class="section" id="engage" aria-labelledby="engage-h">
<h2 id="engage-h">Open an issue, give feedback, or contribute</h2>
<p>
This is an open-source community project under the Cisco DevNet GitHub
organization. Everything — the generators, the static site, the test suite, the
live data — lives in one repository and accepts pull requests.
</p>
<h3>Report a bug or request a feature</h3>
<p>
Use GitHub Issues. Please include the affected release (e.g. 26.1.1), the
page or spec URL, and (for spec issues) the YANG module name.
</p>
<div class="cta-row">
<a class="cta cta-primary" href="https://github.com/CiscoDevNet/cisco-ios-xe-openapi-swagger/issues/new?labels=bug&template=bug_report.md" target="_blank" rel="noopener noreferrer">Open a bug report</a>
<a class="cta cta-secondary" href="https://github.com/CiscoDevNet/cisco-ios-xe-openapi-swagger/issues/new?labels=enhancement&template=feature_request.md" target="_blank" rel="noopener noreferrer">Request a feature</a>
<a class="cta cta-ghost" href="https://github.com/CiscoDevNet/cisco-ios-xe-openapi-swagger/issues" target="_blank" rel="noopener noreferrer">Browse open issues</a>
</div>
<h3>Contribute a fix or a new spec</h3>
<p>
The fastest path is the “add a missing operational spec” walkthrough in
<a href="CONTRIBUTING.md">CONTRIBUTING.md</a>. The big picture:
</p>
<ul>
<li>Branch off <code>main</code>: <code>git checkout -b feat/<short-name></code></li>
<li>Run the matching generator under <code>generators/</code></li>
<li>Re-run <code>scripts/enrich_v2_specs.py</code> so write-op examples stay realistic</li>
<li>Re-run <code>scripts/generate_search_index.py</code></li>
<li>Run <code>python -m pytest tests -q</code> and confirm <strong>143/143</strong></li>
<li>Open a PR with before/after notes — screenshots help for UI changes</li>
</ul>
<div class="cta-row">
<a class="cta cta-primary" href="https://github.com/CiscoDevNet/cisco-ios-xe-openapi-swagger" target="_blank" rel="noopener noreferrer">View on GitHub</a>
<a class="cta cta-secondary" href="CONTRIBUTING.md">Read CONTRIBUTING.md</a>
<a class="cta cta-ghost" href="https://github.com/CiscoDevNet/cisco-ios-xe-openapi-swagger/blob/main/CHANGELOG.md" target="_blank" rel="noopener noreferrer">Read the changelog</a>
</div>
<h3>Discuss, ask questions, share use cases</h3>
<p>
For wider IOS XE programmability conversation:
</p>
<ul>
<li><a href="https://github.com/CiscoDevNet/cisco-ios-xe-openapi-swagger/discussions" target="_blank" rel="noopener noreferrer">GitHub Discussions</a> on this repo — design questions, “how do I…”, show-and-tell.</li>
<li><a href="https://developer.cisco.com/" target="_blank" rel="noopener noreferrer">Cisco DevNet</a> — learning labs, sandboxes (incl. always-on Catalyst 9000V).</li>
<li><a href="https://github.com/YangModels/yang" target="_blank" rel="noopener noreferrer">YangModels/yang</a> — the upstream source of every model this site ingests; issues with the YANG models themselves belong there.</li>
</ul>
</section>
<!-- ==================== CREDITS ==================== -->
<section class="section" id="credits" aria-labelledby="cred-h">
<h2 id="cred-h">Credits & licensing</h2>
<ul>
<li><strong>YANG models</strong> are authored by Cisco and the IETF / OpenConfig communities and published under their respective upstream licenses at <a href="https://github.com/YangModels/yang" target="_blank" rel="noopener noreferrer">YangModels/yang</a>.</li>
<li><strong>This site’s code</strong> (generators, scripts, JS, CSS, HTML) is open source under the repository’s LICENSE.</li>
<li><strong>Swagger UI</strong> © SmartBear Software, used via jsDelivr CDN under the Apache 2.0 license.</li>
<li><strong>Branding.</strong> “Cisco”, “IOS XE”, “Catalyst”, and the Cisco logo are trademarks of Cisco Systems, Inc.</li>
</ul>
<p style="font-size:0.85rem;color:#777;margin-top:14px;">
Not an official Cisco product. Issues with the YANG models or device behavior should
go through Cisco TAC; issues with this site go through the repo’s GitHub Issues.
</p>
</section>
</main>
<script src="about-stats.js"></script>
<script src="assets/js/sw-register.js" defer></script>
</body>
</html>