Repository navigation
Move OpenApi spec generation from swagger and improve documentation for streams - #1591
andreniggemann wants to merge 16 commits into
Conversation
…e api specs. Add option to document SseItems properly
| 'identifier'?: string; | ||
| 'totalAmount'?: number; | ||
| 'number'?: (string | null); | ||
| 'name'?: (string | null); | ||
| 'overDeliveryAmount'?: number; |
There was a problem hiding this comment.
Why is the format broken here?
There was a problem hiding this comment.
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
|
Thanks for the pointers
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. |
|
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. 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
…c using Moryx.Orders.Web
5c9c135 to
c1e77fa
Compare
| </ItemGroup> | ||
|
|
||
| <PropertyGroup> | ||
| <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild> |
There was a problem hiding this comment.
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.
- 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 - 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 - 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
- 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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
- 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.
There was a problem hiding this comment.
- 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.
There was a problem hiding this comment.
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
…n typescript codegen
…ory.Packages.props
Summary
Linked Issues
Relevant logs and/or screenshots
Breaking Changes
Checklist for Submitter
Review
Typical tasks
Obsoleteattributes if necessaryClean code