-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
11 additions
and
60 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,73 +1,24 @@ | ||
| # Siren | ||
| # SpecFlowToMarkdown | ||
|
|
||
| [](https://github.com/gman-au/siren/actions/workflows/nuget.yml) | ||
| [](https://github.com/gman-au/specflow-to-markdown/actions/workflows/nuget.yml) | ||
|
|
||
|  | ||
|  | ||
|
|
||
| ## Summary | ||
| It is a simple command line tool that can be installed from NuGet. | ||
| When run, it will take a C# assembly of POCOs / domain objects, and create an entity relationship (ER) diagram in [Mermaid syntax](https://github.com/mermaid-js/mermaid). | ||
| Properties with the `[Key]` and `[ForeignKey]` data annotations will be also marked accordingly. | ||
| It is a modernised version of the [SpecFlow LivingDoc](https://docs.specflow.org/projects/specflow-livingdoc/en/latest/) engine which takes a test assembly and a set of SpecFlow test results, and renders them in a summarised and presentable format. | ||
|
|
||
| ## Usage | ||
| ### Installation | ||
| You can install the `siren-gen` tool via the following .NET command | ||
| You can install the `specflow-to-markdown` tool via the following .NET command | ||
| ``` | ||
| dotnet tool install -g Gman.Siren | ||
| dotnet tool install -g Gman.SpecFlowToMarkdown | ||
| ``` | ||
| ### Running the tool | ||
| The tool takes two arguments with an optional third: | ||
| The tool takes three arguments: | ||
| ``` | ||
| siren-gen <PATH_TO_POCO_ASSEMBLY> <PATH_TO_OUTPUT_MARKDOWN_FILE> <MARKDOWN_ANCHOR> | ||
| ``` | ||
| - `PATH_TO_POCO_ASSEMBLY` - this will be the location of the built .NET DLL containing the domain objects you wish to map to an ER diagram. Ideally the POCO objects would be in their own assembly. | ||
| - `PATH_TO_OUTPUT_MARKDOWN_FILE` - this points to a file (on your local file system) where the markdown should be generated; includes the full file name. The file _does not have to be a markdown_ (`.md`) file. | ||
| - `MARKDOWN_ANCHOR` - this is useful for updating `README.md` files that may be associated with your domain model (i.e. committed in a git repository). If the markdown anchor is specified, and the output file contains that markdown anchor (for example `"### My Domain Model Diagram"`), then the Siren tool will only add or replace any __existing__ diagram it finds under that anchor, and leave the rest of the document unmodified. | ||
|
|
||
| ## Example | ||
| Take the following classes | ||
| ``` | ||
| public class Customer | ||
| { | ||
| [Key] | ||
| public Guid CustomerId { get; set; } | ||
| public string FirstName { get; set; } | ||
| public string MiddleName { get; set; } | ||
| public string LastName { get; set; } | ||
| } | ||
| public class Order | ||
| { | ||
| [Key] | ||
| public Guid OrderId { get; set; } | ||
| [ForeignKey("CustomerReference")] | ||
| public Guid CustomerId { get; set; } | ||
| public virtual Customer CustomerReference { get; set; } | ||
| public long ReferenceNumber { get; set; } | ||
| public DateTime DatePlaced { get; set; } | ||
| } | ||
| ``` | ||
| When running the tool, the output file should produce the following: | ||
| ```mermaid | ||
| erDiagram | ||
| Customer { | ||
| Guid CustomerId PK | ||
| String FirstName | ||
| String MiddleName | ||
| String LastName | ||
| } | ||
| Order { | ||
| Guid OrderId PK | ||
| Guid CustomerId FK | ||
| Int64 ReferenceNumber | ||
| DateTime DatePlaced | ||
| } | ||
| Customer||--|{Order : "" | ||
| specflow-to-markdown <PATH_TO_TEST_ASSEMBLY> <PATH_TO_TEST_RESULTS_FILE> <PATH_TO_OUTPUT_FILE> | ||
| ``` | ||
| - `PATH_TO_TEST_ASSEMBLY` - this will be the location of the built .NET DLL containing the SpecFlow tests. | ||
| - `PATH_TO_TEST_RESULTS_FILE` - this will be the location of the (JSON) test execution results file. | ||
| - `PATH_TO_OUTPUT_FILE` - this will be the path to the generated output file where the markdown should be generated; includes the full file name. The file _does not have to be a markdown_ (`.md`) file. |