Add Microsoft.Extensions.ApiDesription.Server project and package #10669
There are no files selected for viewing
This file contains hidden or 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 hidden or 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,64 @@ | ||
| <Project> | ||
| <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk" /> | ||
|
|
||
| <PropertyGroup> | ||
| <!-- Execute PopulateNuspec fairly late. --> | ||
| <GenerateNuspecDependsOn>$(GenerateNuspecDependsOn);PopulateNuspec</GenerateNuspecDependsOn> | ||
|
|
||
| <!-- Do not complain about lack of lib folder. --> | ||
| <NoPackageAnalysis>true</NoPackageAnalysis> | ||
|
|
||
| <!-- Included primarily to ensure dotnet-getdocument and GetDocument.Insider can be referenced. --> | ||
| <TargetFrameworks>netcoreapp2.1;net461</TargetFrameworks> | ||
|
|
||
| <Description>MSBuild tasks and targets for build-time Swagger and OpenApi document generation</Description> | ||
| <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences> | ||
| <IncludeBuildOutput>false</IncludeBuildOutput> | ||
| <HasReferenceAssembly>false</HasReferenceAssembly> | ||
| <IncludeSource>false</IncludeSource> | ||
| <NuspecFile>$(MSBuildProjectName).nuspec</NuspecFile> | ||
| <PackageId>$(MSBuildProjectName)</PackageId> | ||
| <PackageTags>MSBuild;Swagger;Open API;code generation;Web API</PackageTags> | ||
| <IsShippingPackage>true</IsShippingPackage> | ||
| <PackageVersion>$(ExperimentalPackageVersion)</PackageVersion> | ||
| <VerifyVersion>false</VerifyVersion> | ||
| <VersionPrefix>$(ExperimentalVersionPrefix)</VersionPrefix> | ||
| <VersionSuffix>$(ExperimentalVersionSuffix)</VersionSuffix> | ||
| </PropertyGroup> | ||
|
|
||
| <ItemGroup> | ||
| <Reference Include="dotnet-getdocument" Condition=" '$(TargetFramework)' == 'netcoreapp2.1' " /> | ||
| <Reference Include="GetDocument.Insider" /> | ||
| </ItemGroup> | ||
|
|
||
| <Target Name="PopulateNuspec"> | ||
| <MSBuild Projects="../../dotnet-getdocument/src/dotnet-getdocument.csproj" | ||
| BuildInParallel="$(BuildInParallel)" | ||
| RemoveProperties="RuntimeIdentifier;TargetFrameworks;TargetFramework" | ||
| Targets="Publish" /> | ||
|
|
||
| <PropertyGroup> | ||
| <NuspecProperties> | ||
| id=$(PackageId); | ||
| artifactsBinDir=$(ArtifactsBinDir); | ||
| authors=$(Authors); | ||
| configuration=$(Configuration); | ||
| copyright=$(Copyright); | ||
| description=$(PackageDescription); | ||
| iconUrl=$(PackageIconUrl); | ||
| licenseUrl=$(PackageLicenseUrl); | ||
| owners=$(Company); | ||
| projectUrl=$(PackageProjectUrl); | ||
| repositoryCommit=$(SourceRevisionId); | ||
| repositoryUrl=$(RepositoryUrl); | ||
| tags=$(PackageTags.Replace(';', ' ')); | ||
| version=$(PackageVersion); | ||
| </NuspecProperties> | ||
| </PropertyGroup> | ||
| </Target> | ||
|
|
||
| <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk" /> | ||
|
|
||
| <Target Name="Compile" /> | ||
| <Target Name="CopyFilesToOutputDirectory" /> | ||
| </Project> | ||
This file contains hidden or 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,27 @@ | ||
| <?xml version="1.0" encoding="utf-8"?> | ||
| <package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd"> | ||
| <metadata minClientVersion="2.8"> | ||
| <id>$id$</id> | ||
| <authors>$authors$</authors> | ||
| <copyright>$copyright$</copyright> | ||
| <description>$description$</description> | ||
| <developmentDependency>true</developmentDependency> | ||
| <iconUrl>$iconUrl$</iconUrl> | ||
| <licenseUrl>$licenseUrl$</licenseUrl> | ||
| <owners>$owners$</owners> | ||
| <projectUrl>$projectUrl$</projectUrl> | ||
| <repository type="git" url="$repositoryUrl$" commit="$repositoryCommit$" /> | ||
| <requireLicenseAcceptance>true</requireLicenseAcceptance> | ||
| <tags>$tags$</tags> | ||
| <version>$version$</version> | ||
| </metadata> | ||
|
|
||
| <files> | ||
| <file src="build\*" target="build" /> | ||
| <file src="buildMultiTargeting\*" target="buildMultiTargeting" /> | ||
| <file src="$artifactsBinDir$\dotnet-getdocument\$configuration$\netcoreapp2.1\publish\*.*" target="tools" /> | ||
| <file src="$artifactsBinDir$\GetDocumentInsider\$configuration$\net461\GetDocument.Insider.*" target="tools\net461" /> | ||
| <file src="$artifactsBinDir$\GetDocumentInsider\x86\$configuration$\net461\GetDocument.Insider.*" target="tools\net461-x86" /> | ||
| <file src="$artifactsBinDir$\GetDocumentInsider\$configuration$\netcoreapp2.1\GetDocument.Insider.*" target="tools\netcoreapp2.1" /> | ||
JunTaoLuo marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| </files> | ||
| </package> | ||
This file contains hidden or 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,34 @@ | ||
| <?xml version="1.0" encoding="utf-8" standalone="no"?> | ||
| <Project> | ||
| <!-- | ||
| Settings users may update as they see fit. | ||
| --> | ||
| <PropertyGroup> | ||
dougbu marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| <!-- | ||
| Options added to the Open API document generation tool ('dotnet-getdocument') command line. Available options | ||
| control console output: 'no-color', 'prefix-output' and 'verbose'. All require a double-dash prefix. | ||
| --> | ||
| <OpenApiGenerateDocumentsOptions Condition=" '$(OpenApiGenerateDocumentsOptions)' == '' "></OpenApiGenerateDocumentsOptions> | ||
|
|
||
| <!-- | ||
| If 'true' (the default), enable generation of Open API documents. Otherwise, this feature is completely disabled. | ||
| This controls whether the 'OpenApiGenerateDocuments' project capability is visible, enables / disables the | ||
| 'GenerateOpenApiDocuments' target and provides the $(OpenApiGenerateDocumentsOnBuild) default. | ||
| --> | ||
| <OpenApiGenerateDocuments Condition=" '$(OpenApiGenerateDocuments)' == '' ">true</OpenApiGenerateDocuments> | ||
|
|
||
| <!-- | ||
| If 'true' (the default if $(OpenApiGenerateDocuments) is 'true'), will generate Open API documents after every | ||
| build. Set to 'false' when targets are invoked from the command line or tied to another target. | ||
| --> | ||
| <OpenApiGenerateDocumentsOnBuild | ||
| Condition=" '$(OpenApiGenerateDocumentsOnBuild)' == '' ">$(OpenApiGenerateDocuments)</OpenApiGenerateDocumentsOnBuild> | ||
|
|
||
| <!-- | ||
| Where to place Open API documents generated from the application. Value is interpreted relative to the project | ||
| folder, unless already an absolute path. | ||
| --> | ||
| <OpenApiDocumentsDirectory | ||
| Condition=" '$(OpenApiDocumentsDirectory)' == '' ">$(BaseIntermediateOutputPath)</OpenApiDocumentsDirectory> | ||
| </PropertyGroup> | ||
| </Project> | ||
This file contains hidden or 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,39 @@ | ||
| <?xml version="1.0" encoding="utf-8" standalone="no"?> | ||
| <Project> | ||
| <PropertyGroup> | ||
| <_OpenApiDocumentsCache>$(BaseIntermediateOutputPath)$(MSBuildProjectName).OpenApiFiles.cache</_OpenApiDocumentsCache> | ||
| </PropertyGroup> | ||
| <ItemGroup Condition=" '$(OpenApiGenerateDocuments)' == 'true' "> | ||
| <ProjectCapability Include="OpenApiGenerateDocuments" /> | ||
| </ItemGroup> | ||
|
|
||
| <Target Name="OpenApiGetDocuments" Returns="@(_OpenApiProjectDocuments)"> | ||
| <ReadLinesFromFile File="$(_OpenApiDocumentsCache)"> | ||
|
There was a problem hiding this comment. Is this actually a cache? or is this just the output of generating the documents? There was a problem hiding this comment. TL;DRIs your question aimed at my naming (and life) choices? I don't see much consistency in how similar MSBuild properties are named and chose something that fit. Make a suggestion if you feel strongly please. DetailsThis file is many things… It's a cache in the sense seen in lots of MSBuild code: It's a way to avoid redoing an action (calling a task, executing a too, whatever). In particular, this file avoids reopening the app whenever a client project calls Yes, as an implementation detail, this file is one of the files written as a result of running the tool. It lists the document files. The file is also like many used in MSBuild code in that it summarizes multiple inputs or outputs of a task or tool. For example, I could do the Finally, this file is the communication mechanism between the |
||
| <Output TaskParameter="Lines" ItemName="_OpenApiProjectDocuments" /> | ||
| </ReadLinesFromFile> | ||
| </Target> | ||
|
|
||
| <Target Name="GenerateOpenApiDocuments" Condition=" '$(OpenApiGenerateDocuments)' == 'true' "> | ||
| <PropertyGroup> | ||
| <_Command>dotnet "$(MSBuildThisFileDirectory)/../tools/dotnet-getdocument.dll" --assembly "$(TargetPath)"</_Command> | ||
| <_Command>$(_Command) --file-list "$(_OpenApiDocumentsCache)" --framework "$(TargetFrameworkMoniker)"</_Command> | ||
| <_Command>$(_Command) --output "$(OpenApiDocumentsDirectory.TrimEnd('\'))" --project "$(MSBuildProjectName)"</_Command> | ||
| <_Command Condition=" '$(ProjectAssetsFile)' != '' ">$(_Command) --assets-file "$(ProjectAssetsFile)"</_Command> | ||
| <_Command Condition=" '$(PlatformTarget)' != '' ">$(_Command) --platform "$(PlatformTarget)"</_Command> | ||
| <_Command Condition=" '$(PlatformTarget)' == '' AND '$(Platform)' != '' ">$(_Command) --platform "$(Platform)"</_Command> | ||
| <_Command Condition=" '$(RuntimeIdentifier)' != '' ">$(_Command) --runtime "$(RuntimeIdentifier)"</_Command> | ||
| <_Command>$(_Command) $(OpenApiGenerateDocumentsOptions)</_Command> | ||
| </PropertyGroup> | ||
|
|
||
| <Message Importance="high" Text="%0AGenerateOpenApiDocuments:" /> | ||
| <Message Importance="high" Text=" $(_Command)" /> | ||
| <Exec Command="$(_Command)" /> | ||
|
There was a problem hiding this comment. What are the caching expectations of this? Should we be adding some things to There was a problem hiding this comment. I have been thinking about I'll add a note to #4923 reminding me to work through the implications and do something. There was a problem hiding this comment. Discussed in person. Right now there is no input/output checking and this command will re-run every time you build, even if the assembly does not change. This is tracked separately and will be improved in the next preview. |
||
| </Target> | ||
|
|
||
| <!-- Unless this is an inner build or default timing is disabled, tie document retrieval into the build. --> | ||
|
|
||
| <Target Name="_GenerateOpenApiDocuments" | ||
| AfterTargets="Build" | ||
| Condition=" '$(OpenApiGenerateDocumentsOnBuild)' == 'true' AND ('$(TargetFramework)' == '' OR '$(TargetFrameworks)' == '') " | ||
| DependsOnTargets="GenerateOpenApiDocuments" /> | ||
| </Project> | ||
This file contains hidden or 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,4 @@ | ||
| <?xml version="1.0" encoding="utf-8" standalone="no"?> | ||
| <Project> | ||
| <Import Project="../build/Microsoft.Extensions.ApiDescription.Server.props" /> | ||
| </Project> |
This file contains hidden or 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,27 @@ | ||
| <?xml version="1.0" encoding="utf-8" standalone="no"?> | ||
| <Project> | ||
| <ItemGroup Condition=" '$(OpenApiGenerateDocuments)' == 'true' "> | ||
| <ProjectCapability Include="OpenApiGenerateDocuments" /> | ||
| </ItemGroup> | ||
|
|
||
| <Target Name="GenerateOpenApiDocuments"> | ||
| <MSBuild Projects="$(MSBuildProjectFile)" | ||
| Targets="GenerateOpenApiDocuments" | ||
| Properties="TargetFramework=$(TargetFrameworks.Split(';')[0])" | ||
| RemoveProperties="RuntimeIdentifier" /> | ||
| </Target> | ||
|
|
||
| <Target Name="_GenerateOpenApiDocuments" | ||
| AfterTargets="Build" | ||
| Condition=" '$(OpenApiGenerateDocumentsOnBuild)' == 'true' " | ||
| DependsOnTargets="GenerateOpenApiDocuments" /> | ||
|
|
||
| <Target Name="OpenApiGetDocuments" Returns="@(_OpenApiProjectDocuments)"> | ||
| <MSBuild Projects="$(MSBuildProjectFile)" | ||
| Targets="OpenApiGetDocuments" | ||
| Properties="TargetFramework=$(TargetFrameworks.Split(';')[0])" | ||
| RemoveProperties="RuntimeIdentifier"> | ||
| <Output TaskParameter="TargetOutputs" ItemName="_OpenApiProjectDocuments" /> | ||
| </MSBuild> | ||
| </Target> | ||
| </Project> |
This file contains hidden or 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 hidden or 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 hidden or 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
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Have you tested this tool when only a .NET Core 3.0 SDK is installed? I didn't see anything which configures rollforward, so I would expect the
dotnet get-document.dllcommand to fail with a "Could not find .NET Core 2.1..." error.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See #10667. That adds
runtimeconfig.template.jsonfiles fordotnet-getdocumentandGetDocument.InsiderThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, I also confirmed this works fine in a 3.0-only environment with 3.0 projects