-
Notifications
You must be signed in to change notification settings - Fork 78
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Adjust outbox and asyncapi plugin docs Signed-off-by: Tomasz Maruszak <[email protected]>
- Loading branch information
Showing
10 changed files
with
371 additions
and
75 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| function ExtractFileNamedFragment($file, $fragmentName) { | ||
| $fragmentLines = New-Object System.Collections.Generic.List[object] | ||
| $fileLines = Get-Content -Path $file | ||
| $markerName = "doc:fragment:$fragmentName"; | ||
| $markerStarted = $false | ||
| foreach ($fileLine in $fileLines) { | ||
| if ($fileLine.Contains($markerName)) { | ||
| $markerStarted = !$markerStarted; | ||
| } | ||
| else { | ||
| if ($markerStarted) { | ||
| $fragmentLines.Add($fileLine) | ||
| } | ||
| } | ||
| } | ||
|
|
||
| return $fragmentLines | ||
| } | ||
|
|
||
| function CountLeadingTabsOrSpaces($lines) { | ||
| $count = -1; | ||
| foreach ($line in $lines) { | ||
| for ($i = 0; $i -lt $line.Length; $i++) { | ||
| $c = $line[$i] | ||
| if (($c -ne "`.") -and ($c -ne " ")) { | ||
| if (($count -eq -1) -or ($i -lt $count)) { | ||
| $count = $i | ||
| } | ||
| break; | ||
| } | ||
| } | ||
| } | ||
| if ($count -eq -1) { | ||
| return 0; | ||
| } | ||
| return $count | ||
| } | ||
|
|
||
| function IdentFragment($lines) { | ||
| $i = CountLeadingTabsOrSpaces $lines | ||
| if ($i -gt 0) { | ||
| return $lines | ForEach-Object { if ($_.Length -gt $i) { $_.Substring($i) } else { $_ } } | ||
| } | ||
| return $lines | ||
| } | ||
|
|
||
| function ProcessMarkdownFileIncludeLine($file, $line, $transformedLines) { | ||
| $found = $line -match '.*\@\[\:cs\]\((.+)\,(.+)\).*' | ||
| if (!$found) { | ||
| throw "Cannot parse fragment include in file $file on line $line" | ||
| } | ||
|
|
||
| $fragmentFilePath = $matches[1] | ||
| $fragmentName = $matches[2] | ||
|
|
||
| $fileFolder = Split-Path -parent $file | ||
| Write-Host "$fileFolder of $file" | ||
|
|
||
| $fragmentLines = ExtractFileNamedFragment "$fileFolder/$fragmentFilePath" $fragmentName | ||
| if ($fragmentLines.Count -gt 0) { | ||
|
|
||
| $fragmentLines = IdentFragment $fragmentLines | ||
|
|
||
| $transformedLines.Add("``````cs") | ||
| $transformedLines.AddRange($fragmentLines); | ||
| $transformedLines.Add("``````") | ||
| } | ||
| } | ||
|
|
||
| function ProcessMarkdown($file, $targetFile) { | ||
| Write-Host "Processing $file into $targetFile ..." | ||
|
|
||
| $templateLines = Get-Content -Path $file | ||
|
|
||
| # Write-Host $templateLines[0] | ||
| $transformedLines = New-Object System.Collections.Generic.List[object] | ||
| foreach ($line in $templateLines) { | ||
| if ($line.Contains("@[:cs](")) { | ||
| ProcessMarkdownFileIncludeLine $file $line $transformedLines | ||
| } | ||
| else { | ||
| $transformedLines.Add($line); | ||
| } | ||
| } | ||
|
|
||
| Set-Content -Path $targetFile -Value ($transformedLines -join "`n") -NoNewline | ||
| } | ||
|
|
||
| # Find files ending in .t.md | ||
| $files = Get-ChildItem -Path '../' -Filter '*.t.md' -Recurse -ErrorAction SilentlyContinue | Select-Object -Property FullName -ExpandProperty FullName | ||
|
|
||
| # For each found file run processing | ||
| foreach ($file in $files) { | ||
| $targetFile = $file.replace('.t.md', '.md'); | ||
|
|
||
| ProcessMarkdown $file $targetFile | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,77 @@ | ||
| # AsyncAPI Specification Plugin for SlimMessageBus <!-- omit in toc --> | ||
|
|
||
| Please read the [Introduction](intro.md) before reading this provider documentation. | ||
|
|
||
| - [Introduction](#introduction) | ||
| - [Configuration](#configuration) | ||
| - [Sample AsyncAPI document](#sample-asyncapi-document) | ||
| - [Documentation](#documentation) | ||
|
|
||
| ## Introduction | ||
|
|
||
| The [`SlimMessageBus.Host.AsyncApi`](https://www.nuget.org/packages/SlimMessageBus.Host.AsyncApi) introduces a document generator for [Saunter](https://github.com/tehmantra/saunter), which enables to generate an [AsyncAPI specification](https://www.asyncapi.com/) from SlimMessageBus. | ||
|
|
||
| ## Configuration | ||
|
|
||
| On the SMB setup, use the `mbb.AddAsyncApiDocumentGenerator()` to add the `IDocumentGenerator` for Saunter library: | ||
|
|
||
| ```cs | ||
| services.AddSlimMessageBus(mbb => | ||
| { | ||
| // Register the IDocumentGenerator for Saunter library | ||
| mbb.AddAsyncApiDocumentGenerator(); | ||
| }); | ||
| ``` | ||
|
|
||
| Then register the Saunter services (in that order): | ||
|
|
||
| @[:cs](../src/Samples/Sample.AsyncApi.Service/Program.cs,ExampleStartup2) | ||
|
|
||
| Saunter also requires to add the following endpoints (consult the Saunter docs): | ||
|
|
||
| ```cs | ||
| // Register AsyncAPI docs via Sauter | ||
| app.MapAsyncApiDocuments(); | ||
| app.MapAsyncApiUi(); | ||
| ``` | ||
|
|
||
| See the [Sample.AsyncApi.Service](../src/Samples/Sample.AsyncApi.Service/) for a complete setup. | ||
|
|
||
| ## Sample AsyncAPI document | ||
|
|
||
| When running the mentioned sample, the AsyncAPI document can be obtained via the following link: | ||
| https://localhost:7252/asyncapi/asyncapi.json | ||
|
|
||
| The generated document for the sample is available [here](../src/Samples/Sample.AsyncApi.Service/asyncapi.json) as well. | ||
|
|
||
| ## Documentation | ||
|
|
||
| The comment and remarks are being taken from the code (for the consumer method and message type): | ||
|
|
||
| ```cs | ||
| /// <summary> | ||
| /// Event when a customer is created within the domain. | ||
| /// </summary> | ||
| /// <param name="Id"></param> | ||
| /// <param name="Firstname"></param> | ||
| /// <param name="Lastname"></param> | ||
| public record CustomerCreatedEvent(Guid Id, string Firstname, string Lastname) : CustomerEvent(Id); | ||
|
|
||
| public class CustomerCreatedEventConsumer : IConsumer<CustomerCreatedEvent> | ||
| { | ||
| /// <summary> | ||
| /// Upon the <see cref="CustomerCreatedEvent"/> will store it with the database. | ||
| /// </summary> | ||
| /// <param name="message"></param> | ||
| /// <returns></returns> | ||
| public Task OnHandle(CustomerCreatedEvent message) { } | ||
| } | ||
| ``` | ||
|
|
||
| Ensure that your project has the `GenerateDocumentationFile` enabled (more [here](https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-7.0&tabs=visual-studio#xml-comments)): | ||
|
|
||
| ```xml | ||
| <PropertyGroup> | ||
| <GenerateDocumentationFile>true</GenerateDocumentationFile> | ||
| </PropertyGroup> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.