shaba/BlazorOpenApi
1
0
Fork 0
mirror of https://github.com/unclshura/BlazorOpenApi.git synced 2025-12-21 09:51:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add Table of Contents feature for improved navigation

Browse Source
This commit is contained in:
Alexander Shabarshov 2025-04-08 11:14:45 +01:00
parent 878a7feded
commit c1cac17c6b
14 changed files with 389 additions and 220 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
BlazorOpenApi/Controls/ComponentsControl.razor
View File

@ -2,33 +2,39 @@
{
@if (Value.Schemas?.Count > 0)
{
<TocMember Title="Schemas">
<h3>Schemas</h3>
@foreach (var (name, val) in Value.Schemas)
{
<h4>@name</h4>
<SchemaControl Value="@val"/>
}
</TocMember>
}
<ResponsesControl Value="@Value.Responses"/>
@if (Value.Parameters?.Count > 0)
{
<TocMember Title="Parameters">
<h3>Parameters</h3>
@foreach (var (name, val) in Value.Parameters)
{
<h4>@name</h4>
<ParametersControl Value="@ToList(val)" />
}
</TocMember>
}
@if (Value.Examples?.Count > 0)
{
<TocMember Title="Examples">
<h3>Examples</h3>
@foreach (var (name, val) in Value.Examples)
{
<ExampleControl Example="@val" Name="@name"/>
}
</TocMember>
}
}

15
BlazorOpenApi/Controls/Expander.razor
View File

@ -1,5 +1,5 @@
<CascadingValue Name="OpenAPIUI_ExpandoTree_Parent" Value="_anchor">
<div class="expander @Class">
<CascadingValue Name="OpenAPIUI_TOC_Parent" Value="_anchor">
<div id="@_anchor" class="expander @Class">
<div class="ex-header @HeaderClass">
@Title
<div onclick="@(() => Toggle())">
@ -36,9 +36,11 @@
public string HeaderClass { get; set; } = "";
[Parameter]
public string Class { get; set; } = "";
[Parameter]
public bool AddToTOC { get; set; } = false;
[CascadingParameter(Name = "OpenAPIUI_ExpandoTree")] public IExpandoTree Tree { get; set; } = null!;
[CascadingParameter(Name = "OpenAPIUI_ExpandoTree_Parent")] public string Parent { get; set; } = "";
[CascadingParameter(Name = "OpenAPIUI_TOC")] public ITableOfContentsTree Tree { get; set; } = null!;
[CascadingParameter(Name = "OpenAPIUI_TOC_Parent")] public string Parent { get; set; } = "";
private string _anchor = $"anc{Random.Shared.Next():X8}";
@ -47,14 +49,19 @@
if (!firstRender)
return;
if (AddToTOC)
{
Tree.Add(Title, _anchor, Parent, Collapsed);
Collapsed = Tree.IsCollapsed(Title);
}
}
void Toggle()
{
Collapsed = !Collapsed;
if ( AddToTOC )
Tree.Collapse(_anchor, Collapsed);
StateHasChanged();
}
}

4
BlazorOpenApi/Controls/HeaderControl.razor
View File

@ -1,5 +1,7 @@
@if (Value != null)
{
<TocMember Title="Header">
<div class="header">
<h1 class="h-title">@Value.Title <span class="h-version">@Value.Version</span></h1>
<div class="h-contact">
@ -33,6 +35,8 @@
<h2>Description</h2>
<MarkdownControl Value="@Value.Description"/>
}
</TocMember>
}
@code {

31
BlazorOpenApi/Controls/OperationControl.razor
View File

@ -1,6 +1,7 @@
@if (Value != null)
{
<div class="op-header @OperationClass" @onclick="Expand">
<TocMember Title="@TocTitle" Anchor="@_anchor">
@if (Value != null)
{
<div id="@_anchor" class="op-header @OperationClass" @onclick="Expand">
<div class="op-type">@Operation</div>
<div class="spacer op-header-text">-</div>
<div class="op-header-text" id="@Value.OperationId">@Endpoint</div>
@ -17,7 +18,7 @@
}
</div>
}
@if (_expanded)
@if (!Collapsed)
{
<svg width="24px" height="24px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M18 15L12 9L6 15" stroke="var(--oa-fg-lighter)" stroke-width="2" />
@ -31,7 +32,7 @@
}
</div>
@if ( _expanded )
@if (!Collapsed)
{
<div class="operation">
@ -44,14 +45,14 @@
<ServersControl Value="@Value.Servers" />
}
<ParametersControl Value="@Value.Parameters"/>
<RequestBodyControl Value="@Value.RequestBody"/>
<ParametersControl Value="@Value.Parameters" />
<RequestBodyControl Value="@Value.RequestBody" />
<ResponsesControl Value="@Value.Responses" />
@if (true)
{
var example = GenerateExampleData();
if ( !string.IsNullOrWhiteSpace(example) )
if (!string.IsNullOrWhiteSpace(example))
{
<div class="example-data">
<h3>Example Data</h3>
@ -63,7 +64,8 @@
}
</div>
}
}
}
</TocMember>
@code {
[Parameter]
@ -73,13 +75,20 @@
[Parameter]
public string Endpoint { get; set; } = "";
[CascadingParameter(Name = "OpenAPIUI_TOC")] public ITableOfContentsTree Tree { get; set; } = null!;
[CascadingParameter(Name = "OpenAPIUI_TOC_Parent")] public string Parent { get; set; } = "";
private string _anchor = $"op_anc{Random.Shared.Next():X8}";
private string TocTitle => $"{Endpoint} - [{Operation.ToString().ToUpper()}] {Value?.Summary}";
private string OperationClass => $"op-{Operation.ToString().ToLower()}";
private bool _expanded = true;
private bool Collapsed => Tree.IsCollapsed(_anchor);
private void Expand()
{
_expanded = !_expanded;
var collapsed = !Tree.IsCollapsed(_anchor);
Tree.Collapse(_anchor, collapsed);
StateHasChanged();
}

2
BlazorOpenApi/Controls/PathControl.razor
View File

@ -1,5 +1,6 @@
@if (!string.IsNullOrWhiteSpace(Key) || Value != null)
{
<TocMember Title="@Key">
@if (!string.IsNullOrWhiteSpace(@Value?.Summary) || !string.IsNullOrWhiteSpace(Value?.Description))
{
<div class="pa-header">
@ -30,6 +31,7 @@
}
}
</div>
</TocMember>
}
@code {

2
BlazorOpenApi/Controls/ServersControl.razor
View File

@ -1,5 +1,6 @@
@if (Value != null && Value.Count > 0)
{
<TocMember Title="Servers">
<h2>Servers</h2>
<table class="servers">
@foreach (var server in Value)
@ -57,6 +58,7 @@
}
}
</table>
</TocMember>
}
@code {

48
BlazorOpenApi/Controls/TableOfContents.razor Normal file
View File

@ -0,0 +1,48 @@
@inject IJSRuntime _js;
@implements IDisposable
<div class="@Class">
<a @onclick="(async() => await ScrolltoAnchor())">@Title</a>
@foreach (var child in Tree.GetChildren(Anchor))
{
<TableOfContents Title="@child.Name" Anchor="@child.Anchor" class="toc-level" Tree="@Tree"/>
}
</div>
@code{
[Parameter] public string Class { get; set; } = "toc-level";
[Parameter] public string Anchor { get; set; } = "";
[Parameter] public string Title { get; set; } = "";
[Parameter] public ITableOfContentsTree Tree { get; set; } = null!;
private string AdaptedTitle => string.IsNullOrWhiteSpace(Title) ? "Root" : Title;
private bool _initialized;
protected override void OnParametersSet()
{
base.OnParametersSet();
if (Tree != null && !_initialized)
{
Tree.Changed += OnTocChanged;
_initialized = true;
}
}
public void Dispose()
{
if (Tree != null)
{
Tree.Changed -= OnTocChanged;
}
}
private void OnTocChanged(object? sender, EventArgs e)
{
StateHasChanged();
}
private async Task ScrolltoAnchor()
{
await _js.InvokeVoidAsync("ScrollTo", Anchor);
}
}

45
BlazorOpenApi/Controls/TocMember.razor Normal file
View File

@ -0,0 +1,45 @@
@if (string.IsNullOrWhiteSpace(Anchor))
{
<CascadingValue Name="OpenAPIUI_TOC_Parent" Value="@_anchor">
<div id="@_anchor">
@if (ChildContent != null)
{
@ChildContent
}
</div>
</CascadingValue>
}
else
{
<CascadingValue Name="OpenAPIUI_TOC_Parent" Value="@Anchor">
<div>
@if (ChildContent != null)
{
@ChildContent
}
</div>
</CascadingValue>
}
@code{
[Parameter] public string Title { get; set; } = "";
[Parameter] public string Anchor { get; set; } = "";
[Parameter] public bool Collapsed { get; set; }
[Parameter] public RenderFragment? ChildContent { get; set; }
[CascadingParameter(Name = "OpenAPIUI_TOC")] public ITableOfContentsTree Tree { get; set; } = null!;
[CascadingParameter(Name = "OpenAPIUI_TOC_Parent")] public string Parent { get; set; } = "";
private string _anchor = $"anc{Random.Shared.Next():X8}";
protected override void OnAfterRender(bool firstRender)
{
if (!firstRender)
return;
Tree.Add(Title, string.IsNullOrWhiteSpace(Anchor) ? _anchor : Anchor, Parent, Collapsed);
}
}

10
BlazorOpenApi/IExpandoTree.cs → BlazorOpenApi/ITableOfContentsTree.cs
View File

@ -6,21 +6,25 @@ using System.Threading.Tasks;
namespace BlazorOpenApi;
public class ExpandoTreeNode
public class TocTreeNode
{
public string Name { get; set; } = string.Empty;
public string Anchor { get; set; } = string.Empty;
public string ParentAnchor { get; set; } = string.Empty;
public bool Collapsed { get; set; }
public override string ToString() => $"Name: {Name}, Anchor: {Anchor}, ParentAnchor: {ParentAnchor}, Collapsed: {Collapsed}";
}
public interface IExpandoTree
public interface ITableOfContentsTree
{
public event EventHandler Changed;
void Add(string name, string anchor, string parentAnchor, bool collapsed);
void Collapse(string anchor, bool collapsed);
bool IsCollapsed(string anchor);
bool Exists(string anchor);
ExpandoTreeNode[] GetChildren(string anchor);
TocTreeNode[] GetChildren(string anchor);
}
//implement IExpandoTree

21
BlazorOpenApi/OpenAPIUIControl.razor
View File

@ -2,6 +2,7 @@
@using Microsoft.OpenApi.Models
@using Microsoft.OpenApi.Readers
<script src="_content/BlazorOpenApi/js/BlazorOpenAPI.js"></script>
@if (Palette != null )
{
@ -10,29 +11,36 @@
<div class="openapi-ui">
<CascadingValue Value="@_api" IsFixed="true">
<CascadingValue Name="OpenAPIUI_ExpandoTree" Value="_tree" IsFixed="true">
<CascadingValue Name="OpenAPIUI_TOC" Value="@_tree" IsFixed="true">
<TableOfContents Tree="@_tree" />
<HeaderControl Value="@_api.Info" DownloadUrl="@Url" />
<ServersControl Value="@_api.Servers" />
@if (_api.Paths?.Count > 0)
{
<TocMember Title="Endpoints">
<h2>Endpoints</h2>
foreach (var path in _api.Paths)
@foreach (var path in _api.Paths)
{
if (!string.IsNullOrWhiteSpace(path.Key) || path.Value != null)
{
<PathControl Key="@path.Key" Value="@path.Value" />
}
}
</TocMember>
}
@if (_api.Components != null)
{
<TocMember Title="Components">
<h2>Components</h2>
<ComponentsControl Value="@_api.Components" />
</TocMember>
}
</CascadingValue>
</CascadingValue>
</div>
@code {
@ -44,10 +52,17 @@
private string _loadedFor = "";
private OpenApiDocument _api = new();
private IExpandoTree _tree = new ExpandoTree();
private ITableOfContentsTree _tree = new TableOfContentsTree();
private MarkupString PaletteStr => Palette?.AsMarkupString ?? new();
protected override void OnAfterRender(bool firstRender)
{
if (!firstRender)
return;
StateHasChanged();
}
protected override async Task OnParametersSetAsync()
{
var loadedFromUrl = _loadedFor == Url && !string.IsNullOrWhiteSpace(Url);

22
BlazorOpenApi/ExpandoTree.cs → BlazorOpenApi/TableOfContentsTree.cs
View File

@ -4,19 +4,26 @@ using System.Linq;
namespace BlazorOpenApi;
internal class ExpandoTree : IExpandoTree
internal class TableOfContentsTree : ITableOfContentsTree
{
private readonly Dictionary<string, ExpandoTreeNode> _nodes = new();
private readonly Dictionary<string, TocTreeNode> _nodes = new();
private readonly List<string> _order = new();
public event EventHandler Changed;
public void Add(string name, string anchor, string parentAnchor, bool collapsed)
{
if (_nodes.ContainsKey(anchor))
{
throw new InvalidOperationException($"A node with anchor '{anchor}' already exists.");
throw new InvalidOperationException($"A node with anchor '{anchor}' already exists for {name}.");
}
var node = new ExpandoTreeNode
if ( parentAnchor != "" && !_nodes.ContainsKey(parentAnchor))
{
throw new InvalidOperationException($"A parent anchor '{parentAnchor}' is not registered for {name}.");
}
var node = new TocTreeNode
{
Name = name,
Anchor = anchor,
@ -26,6 +33,11 @@ internal class ExpandoTree : IExpandoTree
_nodes[anchor] = node;
_order.Add(anchor);
if ( Changed != null )
{
Changed(this, EventArgs.Empty);
}
}
public void Collapse(string anchor, bool collapsed)
@ -47,7 +59,7 @@ internal class ExpandoTree : IExpandoTree
public bool Exists(string anchor) => _nodes.ContainsKey(anchor);
public ExpandoTreeNode[] GetChildren(string anchor) => _order
public TocTreeNode[] GetChildren(string anchor) => _order
.Where(x => _nodes[x].ParentAnchor == anchor)
.Select(x => _nodes[x])
.ToArray();

7
BlazorOpenApi/wwwroot/css/openapi-ui.css
View File

@ -1,4 +1,9 @@
.descriminator {}
.toc-level {
margin-left: 20px;
}
.descriminator {
}
.example {}
.e-item {}

10
BlazorOpenApi/wwwroot/js/BlazorOpenAPI.js Normal file
View File

@ -0,0 +1,10 @@
function ScrollTo(elementId) {
var element = document.getElementById(elementId);
if (element != null) {
element.scrollIntoView({
block: "start"
// behavior: 'smooth'
});
window.scrollBy(0, -64); // Adjust scrolling with a negative value here
}
}

6
Demo/Shared/MainLayout.razor
View File

@ -20,13 +20,13 @@
<MudSwitch @bind-Value="@IsDarkMode" Color="MudBlazor.Color.Primary" Class="ma-4" T="bool" Label="Dark Mode" />
</div>
</MudDrawer>
<MudMainContent>
<CascadingValue Value="@IsDarkMode">
<MudContainer MaxWidth="MaxWidth.ExtraExtraLarge" Class="pt-2">
<MudMainContent>
<MudContainer MaxWidth="MaxWidth.ExtraExtraLarge">
@Body
</MudContainer>
</CascadingValue>
</MudMainContent>
</CascadingValue>
</MudLayout>
@code {