Skip to content

Move OpenApi spec generation from swagger and improve documentation for streams - #1591

Draft
andreniggemann wants to merge 16 commits into
devfrom
feat/native-openapi
Draft

andreniggemann wants to merge 16 commits into
devfrom
feat/native-openapi

Conversation

@andreniggemann

Copy link
Copy Markdown
Collaborator

Summary

  • Transitions api spec generation to Microsoft.AspNetCore.OpenApi instead of swagger, because it has better support for doc comments and is the new standard for Asp.Net.
  • Add ProducesSseEvent Attribute to document the different data types a stream endpoint can produce depending on the event type
  • Add documentation to the OrderManagement and ProductManagement endpoints

Linked Issues

Relevant logs and/or screenshots

Breaking Changes

Checklist for Submitter

  • I have tested these changes locally
  • I have updated documentation as needed
  • I have added or updated tests as appropriate
  • I have used clear and descriptive commit messages

Review

Typical tasks

  • Merge request is well described
  • Added Obsolete attributes if necessary
  • Critical sections are documented in code
  • Tests available or extended
  • Documentation is created / updated
  • Running in test environment
  • Manual is created / updated
  • Ports to other maintained versions are created

Clean code

  • All unused references are removed
  • Clean code rules are respected with passion (naming, ...)
  • Avoid copy and pasted code snippets

…e api specs.

Add option to document SseItems properly
@dbeuchler
dbeuchler self-requested a review November 4, 2026 09:50
@dbeuchler dbeuchler added documentation Improvements or additions to documentation enhancement New feature or request labels Nov 4, 2026

@dbeuchler dbeuchler left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice addition and makes our API really professional.

Its draft but some comments from me:

Can we get rid of the 14k Lines json in the StartProject?

Comment on lines +11 to +15
'identifier'?: string;
'totalAmount'?: number;
'number'?: (string | null);
'name'?: (string | null);
'overDeliveryAmount'?: number;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the format broken here?

@andreniggemann andreniggemann Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have honestly no clue, why the auto generated code is not formatted properly.
The question I will focus on first is why the OperationModel type is not reused

@andreniggemann

Copy link
Copy Markdown
Collaborator Author

Thanks for the pointers

Can we get rid of the 14k Lines json in the StartProject?

I was experimenting with creating the file during the build. This way we could point the code generator at that file instead of a running instance and we could use git to track if something causes a changes to the api model

@dbeuchler

Copy link
Copy Markdown
Member

Thanks for the pointers

Can we get rid of the 14k Lines json in the StartProject?

I was experimenting with creating the file during the build. This way we could point the code generator at that file instead of a running instance and we could use git to track if something causes a changes to the api model

I would always use the live api to generate the code. The 14k lines is a massive file which have to be taken care of and I think one place (the controller) is enough.

@andreniggemann

Copy link
Copy Markdown
Collaborator Author

Just out of curiosity: Is there a reason you prefer to generate the Typescript from a live application?

The generated spec depends on the JsonSettings in the StartProject and a some types that might be nested deep in some DTO.
Having the Spec build automatically and checked into Git makes unintentional changes easy to spot.

I would also prefer to have the spec collocated with the Controller, but I don't see a practical way to achieve that.

…void introducing a package dependency in Moryx.AspNetCore
…letting

ProducesSseEventAttribute inherit from ProducesResponseTypeAttribute so that it's picked up as a response type.

This includes a weird hack, because the .net10 variant only allows a single response type per response code that we can remove in .net11
</ItemGroup>

<PropertyGroup>
<OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Chiming in on the discussion that started in the main comment section between you @dbeuchler and @andreniggemann about whether the spec should be committed in the repo. I took some time to research and think about my stance so here my findings, that let to the subsequent conclusion.

  1. The use case to generate and commit open API specs is documented and apparently very much in scope from Microsoft
    https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md#generate-openapi-documents-at-build-time
  2. There are precedents from the Microsoft cosmos for repos which commit their specs and hence have bigger repos
    2.1. Azure has a full repo dedicated to their api specs
    https://github.com/Azure/azure-rest-api-specs
    2.2 msgraph does commit their APIs in a similar fashion
    https://github.com/microsoftgraph/msgraph-sdk-powershell/blob/main/openApiDocs/v1.0/Users.yml
  3. I would consider it an additional service for external users (which might not build on .net), to be able to build against our APIs without having even to install the .net runtime
  4. We could add a pipeline step which verifies that a dotnet build, does not create any changes in the respective specification file. This way we and everyone else can actually rely on the fact that the spec is not changed manually and inline with the current API

These findings lead me to the opinion that I am in favour of having the spec documented.
Two suggestions:

  • Can we get the verification to prevent manual changes in the pipeline before/together with merging this?
  • Can we place/name the file in a way that does not couple it to the start project but rather to the repository?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have some more to add:

  • Can we split the files into the corresponding controllers?
  • Do we have to commit the file to achieve the comparison for a build-verification step? (e.g. on PR only)
  • Can we reduce the boilerplate and workaround logic in start project?
  • Must it be an StartProject automatism?

@andreniggemann andreniggemann Nov 5, 2026 •

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Can we split the files into the corresponding controllers
  • Must it be an StartProject automatism?

I don't think we can. The way the build step works is by basically starting the StartProject to create the Endpoints like they are in real applications with everything that goes into that (JsonSettings etc.).
Additionally we need a single API spec as a result so that our ng-openapi-gen process works.

  • Do we have to commit the file to achieve the comparison for a build-verification step? (e.g. on PR only)

We need to store them somewhere. We could put them into an external service (for example an external Blob Storage or an external repo like Microsoft does it. The difficulty is finding the correct version to compare to.

  • Can we reduce the boilerplate and workaround logic in start project?

We can reduce it considerably, because stuff like the yaml endpoint, is singlehandedly responsible for half the additional LOC, has just been put there as a proof of concept.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Can we get the verification to prevent manual changes in the pipeline before/together with merging this?

The verification step should be easy enough to setup, either using git directly or using a dedicated tool like https://www.oasdiff.com/docs/github-action that might give more insights.

  • Can we place/name the file in a way that does not couple it to the start project but rather to the repository?
  • I think we are free to change the location to any place we like.
  • We could also change the output to yaml with a couple of lines of code to be consistent with the way Microsoft does it in the examples you gave.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like it! I propose either somewhere in docs or repo root and I also like your yaml suggestion if our client generators can use that too ☺️
The tool you linked looks to be more than sufficient and free withou much impact as long as we only use the github action. I would like that as well. The mention inline github diff support. This would mark issues right in the PR if I get it correctly which would be a visible benefit 👍☺️

* Move schema generation output to /schemas and generate yaml at build time
* Cleanup Program.cs by removing unused code and moving complexity to Moryx.AspNetCore.OpenApi

Notes:
* The current yaml at buildtime is a workaround. Microsoft is aiming to allow yaml at buildtime in the future
* I verified that ng-openapi-gen produces exactly the sameoutput with the yaml spec

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants