diff --git a/Documentation/README.md b/Documentation/README.md index dfaa201..a722aa3 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -5,6 +5,10 @@ To enlist public API, we use the following tool: ```csharp +using Synergy.Documentation.Api; + +namespace Synergy.Documentation.Tests.Architecture.Public; + [UsesVerify] public class Api { @@ -12,9 +16,7 @@ public class Api public async Task Generate() { var assembly = typeof(ApiDescription).Assembly; - var publicApi = ApiDescription.GenerateFor(assembly); - await Verifier.Verify(publicApi, "md") .UseMethodName("of." + assembly.GetName().Name); } diff --git a/Documentation/Synergy.Documentation.Tests/Architecture/Public/Api.cs b/Documentation/Synergy.Documentation.Tests/Architecture/Public/Api.cs index 52d5b08..e9c3b8c 100644 --- a/Documentation/Synergy.Documentation.Tests/Architecture/Public/Api.cs +++ b/Documentation/Synergy.Documentation.Tests/Architecture/Public/Api.cs @@ -8,15 +8,9 @@ public class Api [Fact] public async Task Generate() { - // ARRANGE var assembly = typeof(ApiDescription).Assembly; - - // ACT var publicApi = ApiDescription.GenerateFor(assembly); - - // ASSERT await Verifier.Verify(publicApi, "md") - .UseMethodName("of." + assembly.GetName() - .Name); + .UseMethodName("of." + assembly.GetName().Name); } } \ No newline at end of file diff --git a/Documentation/Synergy.Documentation.Tests/Docs/README.Generate.cs b/Documentation/Synergy.Documentation.Tests/Docs/README.Generate.cs index df3c2d7..ec1a8d5 100644 --- a/Documentation/Synergy.Documentation.Tests/Docs/README.Generate.cs +++ b/Documentation/Synergy.Documentation.Tests/Docs/README.Generate.cs @@ -5,34 +5,35 @@ namespace Synergy.Documentation.Tests.Docs; partial class README { - private static CodeFile ReadmeFile => CodeFolder.Current().Up(2).File($"{nameof(README)}.md"); + private static readonly CodeFile readmeFile = CodeFolder.Current().Up(2).File($"{nameof(README)}.md"); + private readonly CodeFolder architectureFolder = CodeFolder.Current().Up().Sub("Architecture"); // TODO: Marcin Celej [from: Marcin Celej on: 06-01-2024]: Add here reading file path through [SourceFile] from Synergy.Documentation.Annotations - private static CodeFile Api => CodeFolder.Current().Up().Sub("Architecture").Sub("Public").File("Api.cs"); - private Markdown.Link ApiLink => Markdown.Link.To(Api).From(ReadmeFile); + private CodeFile Api => this.architectureFolder.Sub("Public").File("Api.cs"); + private Markdown.Link ApiLink => Markdown.Link.To(Api).RelativeFrom(readmeFile); - private static CodeFile ApiForSynergyDocs => CodeFolder.Current().Up().Sub("Architecture").Sub("Public").File("Api.of.Synergy.Documentation.verified.md"); - private Markdown.Link ApiForSynergyDocsLink => Markdown.Link.To(ApiForSynergyDocs).From(ReadmeFile); + private CodeFile ApiForSynergyDocs => this.architectureFolder.Sub("Public").File("Api.of.Synergy.Documentation.verified.md"); + private Markdown.Link ApiForSynergyDocsLink => Markdown.Link.To(ApiForSynergyDocs).RelativeFrom(readmeFile); - private static CodeFile Package => CodeFolder.Current().Up().Sub("Architecture").Sub("Public").File("Package.cs"); - private Markdown.Link PackageLink => Markdown.Link.To(Package).From(ReadmeFile); + private CodeFile Package => this.architectureFolder.Sub("Public").File("Package.cs"); + private Markdown.Link PackageLink => Markdown.Link.To(Package).RelativeFrom(readmeFile); - private static CodeFile Todos => CodeFolder.Current().Up().Sub("Architecture").Sub("Debt").File("Todos.cs"); - private Markdown.Link TodosLink => Markdown.Link.To(Todos).From(ReadmeFile); + private CodeFile Todos => this.architectureFolder.Sub("Debt").File("Todos.cs"); + private Markdown.Link TodosLink => Markdown.Link.To(Todos).RelativeFrom(README.readmeFile); - private static CodeFile TodosDebt => CodeFolder.Current().Up().Sub("Architecture").Sub("Debt").File("Todos.Technical.Debt.verified.md"); - private Markdown.Link TodosDebtLink => Markdown.Link.To(TodosDebt).From(ReadmeFile); + private CodeFile TodosDebt => this.architectureFolder.Sub("Debt").File("Todos.Technical.Debt.verified.md"); + private Markdown.Link TodosDebtLink => Markdown.Link.To(TodosDebt).RelativeFrom(README.readmeFile); - private static CodeFile Relations => CodeFolder.Current().Up().Sub("Architecture").Sub("Dependencies").File("Relations.cs"); - private Markdown.Link RelationsLink => Markdown.Link.To(Relations).From(ReadmeFile); + private CodeFile Relations => this.architectureFolder.Sub("Dependencies").File("Relations.cs"); + private Markdown.Link RelationsLink => Markdown.Link.To(Relations).RelativeFrom(README.readmeFile); - private static CodeFile RelationsOfMarkdown => CodeFolder.Current().Up().Sub("Architecture").Sub("Dependencies").File("Relations.of.Markdown.verified.md"); - private Markdown.Link RelationsOfMarkdownLink => Markdown.Link.To(RelationsOfMarkdown).From(ReadmeFile); + private CodeFile RelationsOfMarkdown => this.architectureFolder.Sub("Dependencies").File("Relations.of.Markdown.verified.md"); + private Markdown.Link RelationsOfMarkdownLink => Markdown.Link.To(RelationsOfMarkdown).RelativeFrom(README.readmeFile); [Fact] public void Generate() { var content = this.TransformText(); - File.WriteAllText(README.ReadmeFile.FilePath, content); + File.WriteAllText(readmeFile.FilePath, content); } } \ No newline at end of file diff --git a/Documentation/Synergy.Documentation.Tests/Docs/README.cs b/Documentation/Synergy.Documentation.Tests/Docs/README.cs index 0f30f37..941d39f 100644 --- a/Documentation/Synergy.Documentation.Tests/Docs/README.cs +++ b/Documentation/Synergy.Documentation.Tests/Docs/README.cs @@ -25,58 +25,65 @@ public partial class README : READMEBase /// public virtual string TransformText() { - this.Write("# Synergy.Documentation nuget package\r\n\r\n## Enlisting Public API\r\n\r\nTo enlist public API, we use the following tool:\r\n\r\n```csharp\r\n[UsesVerify]\r\npublic class Api\r\n{\r\n [Fact]\r\n public async Task Generate()\r\n {\r\n var assembly = typeof(ApiDescription).Assembly;\r\n\r\n var publicApi = ApiDescription.GenerateFor(assembly);\r\n\r\n await Verifier.Verify(publicApi, \"md\")\r\n .UseMethodName(\"of.\" + assembly.GetName().Name);\r\n }\r\n}\r\n```\r\n\r\nFor sample code, please check: "); + this.Write("# Synergy.Documentation nuget package\r\n\r\n## Enlisting Public API\r\n\r\nTo enlist public API, we use the following tool:\r\n\r\n```csharp\r\n"); - #line 26 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" + #line 10 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" + this.Write(this.ToStringHelper.ToStringWithCulture(this.Api.ReadAllText())); + + #line default + #line hidden + this.Write("\r\n```\r\n\r\nFor sample code, please check: "); + + #line 13 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" this.Write(this.ToStringHelper.ToStringWithCulture(this.ApiLink)); #line default #line hidden this.Write("\r\n\r\nTo see the results, please check: "); - #line 28 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" + #line 15 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" this.Write(this.ToStringHelper.ToStringWithCulture(this.ApiForSynergyDocsLink)); #line default #line hidden this.Write("\r\n\r\n**Note:**\r\n\r\nWhen you expose your public API, you should be aware how it looks like from the outside - "); - #line 32 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" + #line 19 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" this.Write(this.ToStringHelper.ToStringWithCulture(this.ApiLink)); #line default #line hidden this.Write(".\r\n\r\nWhen you consume some external library - you can enlist its public API and see how it looks like - "); - #line 34 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" + #line 21 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" this.Write(this.ToStringHelper.ToStringWithCulture(this.PackageLink)); #line default #line hidden this.Write(".\r\n\r\n## Managing technical debt\r\n\r\nTo manage technical debt, we use the following tool:\r\n\r\n```csharp\r\n[UsesVerify]\r\npublic class Todos\r\n{\r\n [Fact]\r\n public async Task Generate()\r\n {\r\n var rootFolder = CodeFolder.Current()\r\n .Up(3);\r\n var technicalDebt = TodoExplorer.DebtFor(\"Synergy.Contracts\", rootFolder);\r\n\r\n await Verifier\r\n .Verify(technicalDebt, \"md\")\r\n .UseMethodName(\"Technical.Debt\");\r\n }\r\n}\r\n```\r\n\r\nFor sample code, please check: "); - #line 58 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" + #line 45 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" this.Write(this.ToStringHelper.ToStringWithCulture(this.TodosLink)); #line default #line hidden this.Write("\r\n\r\nTo see the results, please check: "); - #line 60 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" + #line 47 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" this.Write(this.ToStringHelper.ToStringWithCulture(this.TodosDebtLink)); #line default #line hidden this.Write("\r\n\r\n**Note:** \r\n\r\nBasic idea of using this test is to have a list of all technical debt in the project.\r\nEach time developer adds a new technical debt, he should re-run this test otherwise it will fail on the CI.\r\nWhen all tech debt for the project is materialized in single file - we can start working on it.\r\nIt also helps to keep track of all tech debt in the project.\r\nMoreover, it is much easier to spot new technical debt during the code review.\r\n\r\n## Enlisting dependencies of a class\r\n\r\nTo document dependencies of a specific class, we use the following tool:\r\n\r\n```csharp\r\n[UsesVerify]\r\npublic class Relations\r\n{\r\n [Theory]\r\n [InlineData(typeof(Markdown))]\r\n [InlineData(typeof(Markdown.Document))]\r\n public async Task Generate(Type type)\r\n {\r\n // ARRANGE\r\n var dependencies = Synergy.Documentation.Api.Dependencies.Of(type);\r\n\r\n // ACT\r\n var publicApi = ApiDescription.GenerateFor(dependencies);\r\n\r\n // ASSERT\r\n await Verifier.Verify(publicApi, \"md\")\r\n .UseMethodName(\"of.\" + type.Name);\r\n }\r\n}\r\n```\r\n\r\nFor sample code, please check: "); - #line 96 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" + #line 83 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" this.Write(this.ToStringHelper.ToStringWithCulture(this.RelationsLink)); #line default #line hidden this.Write("\r\n\r\nTo see the results, please check: "); - #line 98 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" + #line 85 "C:\Projects\Synergy\framework\src\Documentation\Synergy.Documentation.Tests\Docs\README.tt" this.Write(this.ToStringHelper.ToStringWithCulture(this.RelationsOfMarkdownLink)); #line default diff --git a/Documentation/Synergy.Documentation.Tests/Docs/README.tt b/Documentation/Synergy.Documentation.Tests/Docs/README.tt index 5c32eeb..2671705 100644 --- a/Documentation/Synergy.Documentation.Tests/Docs/README.tt +++ b/Documentation/Synergy.Documentation.Tests/Docs/README.tt @@ -7,20 +7,7 @@ To enlist public API, we use the following tool: ```csharp -[UsesVerify] -public class Api -{ - [Fact] - public async Task Generate() - { - var assembly = typeof(ApiDescription).Assembly; - - var publicApi = ApiDescription.GenerateFor(assembly); - - await Verifier.Verify(publicApi, "md") - .UseMethodName("of." + assembly.GetName().Name); - } -} +<#= this.Api.ReadAllText() #> ``` For sample code, please check: <#= this.ApiLink #> diff --git a/Web/Sample/Synergy.Sample.Web.API.Tests/Users/Users.md b/Web/Sample/Synergy.Sample.Web.API.Tests/Users/Users.md index 36e09e7..0f22c75 100644 --- a/Web/Sample/Synergy.Sample.Web.API.Tests/Users/Users.md +++ b/Web/Sample/Synergy.Sample.Web.API.Tests/Users/Users.md @@ -95,7 +95,7 @@ Content-Length: 129 ### 2.2. Get created user pointed by "Location" header (1 request) -### 2.2.2. Request to [Get user located at http://localhost/api/v1/users/275163fbe1b149e2adbddd0af5d27404] +### 2.2.2. Request to [Get user located at http://localhost/api/v1/users/fc34987948684ac8ab5becc774173947] - Request ``` @@ -137,7 +137,7 @@ Content-Length: 129 ### 3.1. Get user by id (1 request) -### 3.1.1. Request to [Get user with id "275163fbe1b149e2adbddd0af5d27404"] +### 3.1.1. Request to [Get user with id "fc34987948684ac8ab5becc774173947"] - Request ``` @@ -391,7 +391,7 @@ Content-Length: 351 ### 6.1. Delete user by id (1 request) -### 6.1.1. Request to [Delete user with id "275163fbe1b149e2adbddd0af5d27404"] +### 6.1.1. Request to [Delete user with id "fc34987948684ac8ab5becc774173947"] - Request ``` @@ -418,7 +418,7 @@ Content-Length: 2 ### 6.2. Try to get the deleted user (1 request) -### 6.2.2. Request to [Get user with id "275163fbe1b149e2adbddd0af5d27404"] +### 6.2.2. Request to [Get user with id "fc34987948684ac8ab5becc774173947"] - Request ```