-
Notifications
You must be signed in to change notification settings - Fork 22
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(api-hub): generate open api specs for portal services (#1030)
* adjust ms build processes to generate open api file for web service projects * add documentation for the process of generating the open api files * adjust validation of settings * add possibility to skip the settings validation on startup for test projects * update framework version --------- Refs: #1021 Co-authored-by: Norbert Truchsess <[email protected]> Reviewed-by: Norbert Truchsess <[email protected]> Reviewed-by: Evelyn Gurschler <[email protected]>
- Loading branch information
1 parent
f8c155c
commit 67cc761
Showing
108 changed files
with
17,103 additions
and
1,249 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
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
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,45 @@ | ||
| # OpenAPI Provisioning | ||
|
|
||
| The provisioning of the open api files for each service of the portal is done via the ms build process of each Service project. | ||
|
|
||
| ## Setup to generate open api files | ||
|
|
||
| The following setup was done for all existing services of the portal which currently are: | ||
|
|
||
| - `Adminstiration Service` | ||
| - `Apps Service` | ||
| - `Notification Service` | ||
| - `Registration Service` | ||
| - `Services Service` | ||
|
|
||
| ### Setup dotnet tool | ||
|
|
||
| To be able to run the `dotnet tool run swagger tofile` command it needs to be installed for the project. Therefor a `dotnet-tools.json` file was created within a `.config` directory. This file includes a reference to a nuget package which is needed to execute the command. | ||
|
|
||
| ### Setup csproj | ||
|
|
||
| To execute the generation of the open api document the .csproj file of the project was adjusted as follows: | ||
|
|
||
| ```xml | ||
| <Target Name="openapi" AfterTargets="Build"> | ||
| <Message Text="generating openapi v$(Version)" Importance="high" /> | ||
| <Exec Command="dotnet tool restore" /> | ||
| <Exec Command="dotnet tool run swagger tofile --yaml --output ../../../docs/api/$(AssemblyName).yaml $(OutputPath)$(AssemblyName).dll v$(Version)" EnvironmentVariables="DOTNET_ROLL_FORWARD=LatestMajor;SKIP_CONFIGURATION_VALIDATION=true;MVC_ROUTING_BASEPATH=api/administration" /> | ||
| </Target> | ||
| ``` | ||
|
|
||
| The configuration runs after the build of the project, it executes a `dotnet tool restore` which is needed to than run the command to generate the open api file. | ||
|
|
||
| The `dotnet tool run swagger tofile` is executed with the following parameters: | ||
|
|
||
| 1. `--yaml` sets the filetype to yaml, an alternative would be to remove the parameter, the file would than be generated as a json | ||
|
|
||
| 2. `--ouput ../../../docs/api/$(AssemblyName).yaml $(OutputPath)$(AssemblyName).dll v$(Version)` sets the ouput path for the file and specifies the version of the swagger file that should be taken | ||
|
|
||
| > **IMPORTANT**: the version set for the output must(!) match with the version which is specified in the `Program.cs` more under [Setup Program](#setup-program) | ||
| 1. `EnvironmentVariables="DOTNET_ROLL_FORWARD=LatestMajor;SKIP_CONFIGURATION_VALIDATION=true"` sets the environment variables to start up the program. With the variable `SKIP_CONFIGURATION_VALIDATION` the configuration validation is skipped when starting the application | ||
|
|
||
| ## Setup Program | ||
|
|
||
| To get the version of the assembly which is used in the csproj file with `$(Version)` an extension was introduced. By calling `AssemblyExtension.GetApplicationVersion()` in the Program.cs the entry assembly will be taken, and the `InformationalVersion` will be taken. |
Oops, something went wrong.