#196 Publish a global dotnet tool (AsyncAPI.Saunter.Generator.Cli) by smoerijf · Pull Request #217 · asyncapi/saunter

smoerijf · 2024-07-06T12:30:44Z

Description
tool to generate an asyncApi spec from a startup assembly.
Implementation inspired by https://www.nuget.org/packages/Swashbuckle.AspNetCore.Cli

I already took the freedom to upload to nuget: https://www.nuget.org/packages/AsyncAPI.Saunter.Generator.Cli

Uses the Lego AsyncApi.net nuget packages to also export yml spec files.

Related issue(s)
#196

smoerijf · 2024-07-06T13:07:06Z

.editorconfig

 # XML project files
 [*.{csproj,vbproj,vcxproj,vcxproj.filters,proj,projitems,shproj}]
-indent_size = 4
+indent_size = 2


current files were using a size of 2 and lf line endings, so I changed it (because my VS defaults are different)

…uments, default all. Added support for env vars

…capi document

…data to package

… parameter handling

yurvon-screamo

It's a great decision, and you're well on your way, but the product is not yet ready for release to users.

src/AsyncAPI.Saunter.Generator.Cli/Commands/Tofile.cs

src/AsyncAPI.Saunter.Generator.Cli/AsyncAPI.Saunter.Generator.Cli.csproj

src/AsyncAPI.Saunter.Generator.Cli/SwashbuckleImport/readme.md

src/AsyncAPI.Saunter.Generator.Cli/readme.md

test/AsyncAPI.Saunter.Generator.Cli.Tests/PackAndInstallLocalTests.cs

test/AsyncAPI.Saunter.Generator.Cli.Tests/DotnetCliToolTests.cs

smoerijf · 2024-07-08T12:10:39Z

I'm happy to comply with the new formatting style rules or with changes from PRs like #201

@yurvon-screamo is it possible to assign issues to me? #196 #197 #207 (Or can you assign rights if I may do that myself?)

yurvon-screamo · 2024-07-08T14:10:52Z

I'm happy to comply with the new formatting style rules or with changes from PRs like #201

@yurvon-screamo is it possible to assign issues to me? #196 #197 #207 (Or can you assign rights if I may do that myself?)

don't rush too much, I'm finishing the translation to the LEGO library, better wait for it so as not to solve a million conflicts...

smoerijf · 2024-07-08T15:23:44Z

I didn't know you were working on the LEGO migration, just saw your draft PR. Very nice to see!

If any more conflicts arise, I'll resolve them too.

…Publish-a-global-dotnet-tool # Conflicts: # .github/workflows/ci.yaml # Saunter.sln

…achbuckle copy/paste code

smoerijf · 2024-07-11T21:29:01Z

I think all remarks have been addressed. All the working parts are unit tested. I've also made changes to the ci workflows to run all tests (not just the 2 projects that already existed.) and to also release based on the solution, not just the main Saunter csproj (release pipeline changes are not tested)

…at failed to generate specs, fixed now. Added an external nuget dependancy to the example project (nlog) because that made spec generation fail, fixed now. And now also testing both .NET6 & .NET8

smoerijf · 2024-07-13T18:14:16Z

examples/StreetlightsAPI.TopLevelStatement/StreetlightsAPI.TopLevelStatement.csproj

+  <PropertyGroup>
+    <!-- This project is targeting .NET8 intentionally (The 'old school' Startup-class project is .NET6), to prove that
+         the AsyncAPI.Saunter.Generator.Cli tool can generate specs for projects targetting .NET6 and .NET8. -->
+    <TargetFramework>net8.0</TargetFramework>


Added 2nd example project (also to be used in integration test) because Top Level Statement projects initially didn't work with the Generator.Cli tool. Now it does work too. And proves using integration test that both NET6 & NET8 targets work.

7CLewis · 2024-08-07T17:06:38Z

@yurvon-screamo Any idea when this might get merged and added? Would love to be able to use this tool.

7CLewis · 2024-08-10T18:30:01Z

@smoerijf Your prerelease version on NuGet does not work with function apps. They do not have a standard Startup.cs file, and it seems to be having issues with that.

smoerijf · 2024-08-11T07:22:29Z

@smoerijf Your prerelease version on NuGet does not work with function apps. They do not have a standard Startup.cs file, and it seems to be having issues with that.

Thank you for trying the prerelease. I've never worked with function apps, is that the same as Azure functions? Don't those apps have a Main or ServiceProvider?

How this tools works: Inspect the DLL to find the main entrypoint and build the IServiceProvider. That IServiceProvider is used to create instances of Saunter's IAsyncApiDocumentProvider class. This is the same approach as Entity Framework Migrations (I'm using an EF nuget package to extract the IServiceProvider from the DLL). So this tool should support the same type of apps as EF does.

As I've no experience at all with function apps, I've no idea how they are structured or how Saunter library integrates with them. If they work with EF migrations, could you share a (minimal) example with Saunter?

7CLewis · 2024-08-12T22:36:25Z

@smoerijf Your prerelease version on NuGet does not work with function apps. They do not have a standard Startup.cs file, and it seems to be having issues with that.

Thank you for trying the prerelease. I've never worked with function apps, is that the same as Azure functions? Don't those apps have a Main or ServiceProvider?

How this tools works: Inspect the DLL to find the main entrypoint and build the IServiceProvider. That IServiceProvider is used to create instances of Saunter's IAsyncApiDocumentProvider class. This is the same approach as Entity Framework Migrations (I'm using an EF nuget package to extract the IServiceProvider from the DLL). So this tool should support the same type of apps as EF does.

As I've no experience at all with function apps, I've no idea how they are structured or how Saunter library integrates with them. If they work with EF migrations, could you share a (minimal) example with Saunter?

Here's a minimal example: https://github.com/7CLewis/SaunterFunctionApp. If you Build that and then try to run dotnet asyncapi tofile [path_to_repo]\bin\Debug\net6.0\SaunterFunctionApp.dll --format "json", it'll give that error I mentioned.

Azure Function apps do not have a normal Startup like regular apps, as you can see from that example. I haven't tried EF Migrations with AzFuncs, so I can't speak to that.

drdamour · 2024-08-12T22:58:29Z

@smoerijf when u do ef core in AzF where startup doesn't exists you have to offer up a Design Time Factory as doc'd here https://learn.microsoft.com/en-us/ef/core/cli/dbcontext-creation?tabs=dotnet-core-cli#from-a-design-time-factory

could something similar be done in saunter where before looking for startup stuff...it would look for a specific public type implementing an interface.

mrfelton · 2025-04-22T13:52:48Z

Any chance of publishing a newer/alternatve (prerelease) version of this that targets net9.0?

.editorconfig

VisualBean · 2025-04-24T13:53:44Z

src/AsyncAPI.Saunter.Generator.Cli/ToFile/AsyncApiDocumentExtractor.cs

+
+            var schema = documentProvider.GetDocument(asyncApiOptions, prototype);
+            var asyncApiSchemaJson = documentSerializer.Serialize(schema);
+            var asyncApiDocument = new AsyncApiStringReader().Read(asyncApiSchemaJson, out var diagnostic);


note that this technically read 2.6 and not 2.4 which has 'some' discrepancies.
Not that there is much to do about it.
Hopefully ill be able to get some time in to work on moving saunter forward to V3 (which is now supported by AsyncAPI.Net)

mrfelton · 2025-04-24T16:11:12Z

src/AsyncAPI.Saunter.Generator.Cli/ToFile/AsyncApiDocumentExtractor.cs

+            }
+            else
+            {
+                logger.LogCritical($"AsyncAPI documents found. Known named document(s): {string.Join(", ", asyncApiOptions.NamedApis.Keys)}.");


We're not using AssemblyMarkerTypes to define our APIs, but rather we are using Saunter to build up the document dynamically based on inspecting our own EventBus implementation, via a custom document generator. This isn't working for that use case.

mrfelton · 2025-04-24T19:14:57Z

This seems to be stripping out the messageId property from the message definitions, which is a required property in the 2.x version of asyncapi and so the output produced from the cli is an invalid document. The messageId is included when my app renders the document. The messageId is required for various sets of tooling to work with v2.x schemas

VisualBean · 2025-04-24T19:26:21Z

This seems to be stripping out the messageId property from the message definitions, which is a required property in the 2.x version of asyncapi and so the output produced from the cli is an invalid document. The messageId is included when my app renders the document. The messageId is required for various sets of tooling to work with v2.x schemas

MessageId has never been required as far as I know. In terms of the specification itself.

Docs specifically state "Tools and libraries MAY use messageId to..."

But this is somewhat besides the point. It shouldn't be stripping anything. My point is that its technically not invalid documents without messageId

mrfelton · 2025-04-24T19:39:52Z

It looks like it's not being included in the serialised output, upstream, here: https://github.com/LEGO/AsyncAPI.NET/blob/main/src/LEGO.AsyncAPI/Models/AsyncApiMessage.cs#L118

MessageId has never been required as far as I know. In terms of the specification itself.

I see. So I think there is also an issue in the tool I'm using - The EventCatalog asyncapi generator. Specifically, here https://github.com/event-catalog/generators/blob/85f04c0086e6eac77c3023de8cc5dc3051df5d0b/packages/generator-asyncapi/src/index.ts#L296, where it's expected that messageid is set.

VisualBean · 2025-04-24T19:43:29Z

It looks like it's not being included in the serialised output, upstream, here: https://github.com/LEGO/AsyncAPI.NET/blob/main/src/LEGO.AsyncAPI/Models/AsyncApiMessage.cs#L118

MessageId has never been required as far as I know. In terms of the specification itself.

I see. So think there is also an issue in the tool I'm using - The EventCatalog asyncapi generator. Specifically, here https://github.com/event-catalog/generators/blob/85f04c0086e6eac77c3023de8cc5dc3051df5d0b/packages/generator-asyncapi/src/index.ts#L296, where it's expected that messageid is set.

Definitely a bug in asyncapi.net.
I'll go and fix this within an hour or so.

Has been fixed now here as of 1.0.1. (The 2.0.0 preview has AsyncAPI V3 support. )
https://www.nuget.org/packages/ByteBard.AsyncAPI.NET/

VisualBean · 2025-04-29T15:48:27Z

src/AsyncAPI.Saunter.Generator.Cli/ToFile/AsyncApiDocumentExtractor.cs

@@ -0,0 +1,72 @@
+using LEGO.AsyncAPI.Models;


The new repo for this is under bytebard rather than LEGO.
Same codebase (direct fork) but actively maintained again (as I'm not at LEGO anymore, and they have dropped maintaining my baby)

Preview has v3 support, while main has a few bug fixes not in the LEGO repo.

Senn Geerts added 6 commits July 6, 2024 14:27

asyncapi#196 Publish a global dotnet tool

6318f80

asyncapi#196 Publish a global dotnet tool -- Api/API casing fix

2162d72

asyncapi#196 .NET8

55895a2

asyncapi#196 .NET6

6ba3409

asyncapi#196 I'd like .NET8 more, request both for ci

74c9cff

asyncapi#196 I'd like .NET8 more, request both for ci?

cc5d952

smoerijf commented Jul 6, 2024

View reviewed changes

Senn Geerts added 8 commits July 6, 2024 17:20

asyncapi#196 Fixed resolving, added support for multiple asyncAPI doc…

569a30a

…uments, default all. Added support for env vars

asyncapi#196 Test for dotnet cli tool, added support for default asyn…

0419101

…capi document

asyncapi#196 Pack_Install_Run_Uninstall Test

b29a1ab

asyncapi#196 Pack_Install_Run_Uninstall fix casing in test, add meta …

12593dc

…data to package

asyncapi#196 fix accident

93dc17e

asyncapi#196 fix warnings, fix permission

e701660

asyncapi#196 unix needs a shebang

d9b558c

asyncapi#196 sourcelink properties

f0af6d1

smoerijf marked this pull request as ready for review July 6, 2024 18:17

smoerijf requested review from VisualBean, m-wild and yurvon-screamo as code owners July 6, 2024 18:17

Senn Geerts added 2 commits July 7, 2024 11:39

asyncapi#196 renamed tool to make up a more logical name, fixed empty…

1ebb77c

… parameter handling

asyncapi#196 fix readme error

ba1e856

smoerijf mentioned this pull request Jul 7, 2024

#197 produce async api documents at build time #218

Closed

yurvon-screamo reviewed Jul 8, 2024

View reviewed changes

Senn Geerts added 4 commits July 8, 2024 20:05

Merge remote-tracking branch 'remotes/origin/main' into asyncapi#196-…

90dcff1

…Publish-a-global-dotnet-tool # Conflicts: # .github/workflows/ci.yaml # Saunter.sln

asyncapi#196 Fixed formatting etc + some PR remarks

a746e4d

asyncapi#196 Tool rewrite to make its components testable, removed Sw…

8e7a01f

…achbuckle copy/paste code

asyncapi#196 formatting

240c9ed

asyncapi#196 release also the CLI tool

72dc742

smoerijf requested a review from yurvon-screamo July 11, 2024 21:25

smoerijf changed the title ~~#196 Publish a global dotnet tool~~ #196 Publish a global dotnet tool (AsyncAPI.Saunter.Generator.Cli) Jul 13, 2024

smoerijf mentioned this pull request Jul 13, 2024

#197 Produce AsyncAPI documents at build time (AsyncAPI.Saunter.Generator.Build) #219

Draft

asyncapi#196 Add example project with top level statement, because th…

7b22ce0

…at failed to generate specs, fixed now. Added an external nuget dependancy to the example project (nlog) because that made spec generation fail, fixed now. And now also testing both .NET6 & .NET8

smoerijf commented Jul 13, 2024

View reviewed changes

Senn Geerts added 9 commits July 13, 2024 20:23

asyncapi#196 Ignore expected warning (ASP0014 needs asyncapi#173)

ba8dd8e

asyncapi#196 formatting and readme wording

3d6c0ea

asyncapi#196 ExitCode test problems

8a4f5c6

asyncapi#196 ExitCode test problems -- the issue is a missing reference

07b4273

asyncapi#196 GetStreamFor logging

e846dd9

asyncapi#196 GetStreamFor try recreate directory?

fc7cccd

asyncapi#196 GetStreamFor try recreate directory??

4f1064e

asyncapi#196 permission issue?

74260a8

asyncapi#196 cleanup csproj

5fe8c6e

VisualBean reviewed Apr 24, 2025

View reviewed changes

.editorconfig Show resolved Hide resolved

VisualBean reviewed Apr 24, 2025

View reviewed changes

mrfelton reviewed Apr 24, 2025

View reviewed changes

VisualBean reviewed Apr 29, 2025

View reviewed changes

Conversation

smoerijf commented Jul 6, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

smoerijf Jul 6, 2024

Choose a reason for hiding this comment

Uh oh!

yurvon-screamo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

smoerijf commented Jul 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yurvon-screamo commented Jul 8, 2024

Uh oh!

smoerijf commented Jul 8, 2024

Uh oh!

smoerijf commented Jul 11, 2024

Uh oh!

smoerijf Jul 13, 2024

Choose a reason for hiding this comment

Uh oh!

7CLewis commented Aug 7, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

7CLewis commented Aug 10, 2024

Uh oh!

smoerijf commented Aug 11, 2024

Uh oh!

7CLewis commented Aug 12, 2024

Uh oh!

drdamour commented Aug 12, 2024

Uh oh!

mrfelton commented Apr 22, 2025

Uh oh!

Uh oh!

VisualBean Apr 24, 2025

Choose a reason for hiding this comment

Uh oh!

mrfelton Apr 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrfelton commented Apr 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

VisualBean commented Apr 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mrfelton commented Apr 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

VisualBean commented Apr 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

VisualBean Apr 29, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Comments

smoerijf commented Jul 6, 2024 •

edited

Loading

yurvon-screamo left a comment •

edited

Loading

smoerijf commented Jul 8, 2024 •

edited

Loading

7CLewis commented Aug 7, 2024 •

edited

Loading

mrfelton Apr 24, 2025 •

edited

Loading

mrfelton commented Apr 24, 2025 •

edited

Loading

VisualBean commented Apr 24, 2025 •

edited

Loading

mrfelton commented Apr 24, 2025 •

edited

Loading

VisualBean commented Apr 24, 2025 •

edited

Loading