A Programmer with Microsoft tools

WebAPI2CLI

I need 2 types of documentation:

1. For let people know how to use

2. For the programmers – to understand what the classes are doing

For the first point, documentation to use

a. Github has already the readme.md file that shows details for the repository . What I need is something more- i.e. detailed instruction, FAQ, Author.

b. Github has made easy to make an online site  -by having the docs folder public with his own address. For example, from  https://github.com/ignatandrei/webAPI2CLI/ I can have https://ignatandrei.github.io/WebAPI2CLI/ . Now , the problem is how to concatenate those and put back to site

c. GitHub has also the concept of Actions –i.e.  DevOps integrated.

So –what I have done is to use pandoc , compile all the .md files into html ( and pdf ) and push modifications back to the site.

See https://github.com/ignatandrei/WebAPI2CLI/blob/master/.github/workflows/main.yml

– uses: actions/checkout@v2

– run: |

echo generate help file

mkdir output

git pull

– name: generate html

uses: docker://pandoc/latex:2.9

with: # needs a README in your repo root!

#args: “–standalone –output=output/README.html README.md”

args: “README.md docs/Demo.md docs/FAQ.md docs/Author.md –standalone -f gfm -t html  –toc -o output/output.html –metadata title=WebAPI2CLI”

– name: generate pdf

uses: docker://pandoc/latex:2.9

with: # needs a README in your repo root!

#args: “–standalone –output=output/README.html README.md”

args: “README.md docs/Demo.md docs/FAQ.md docs/Author.md –standalone -f gfm -t pdf  –toc -o output/output.pdf –metadata title=WebAPI2CLI”

– run: |

cp ./output/output.html ./docs/index.html

cp ./output/output.pdf ./docs/Web2CLI.pdf

rm -rf ./output

You can see the results at https://ignatandrei.github.io/WebAPI2CLI/ and the sources at https://github.com/ignatandrei/WebAPI2CLI/tree/master/docs

For the second point, generating documentation from XML Comments in C#

I need some free .NET tool to do this. I did not found. I have hesitated also between https://github.com/EWSoftware/SHFB ( an old friend, but cumbersome ) and https://github.com/dotnet/docfx/ ( a new friend, but still cumbersome)

What I have done is to download docfx, add to the site, follow instructions , modify some of the templates , resist temptation to put everything into docfx ( he kinda want to be all inclusive)

docs_csharp:

# The type of runner that the job will run on

runs-on: windows-latest

steps:

# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it

– uses: actions/checkout@v2

– name: run documentation

run: |

DocumentationSources.bat

rem git config –local user.email “action@github.com”

rem git config –local user.name “GitHub Action”

rem git commit -m “generate documentation sources” -a –allow-empty

shell: cmd

– name: Push changes

uses: ad-m/github-push-action@master

with:

github_token: ${{ secrets.GITHUB_TOKEN }}

You can see the results at https://ignatandrei.github.io/WebAPI2CLI/sitedocs/api/index.html  and sources at https://github.com/ignatandrei/WebAPI2CLI/tree/master/docs/sitedocs

WebAPI2CLI

First implementation was just a bunch a code thrown in an API project. All self contained, all in one WebAPI project.

Some problems that I have faced:

1. The class that executes( the hosted service )  should have access to the address of the server . However, the class is injected at the moment of creating services – and at this time the IServerAddressesFeature do not exists yet.

Solution: Inject at useCLi the IApplicationBuilder to get the services and verify if the adresses are ok:

// in private async void DoWork(object state)

serverAddresses = app.ServerFeatures.Get<IServerAddressesFeature>();

if (serverAddresses == null)

2. But how to get the instance of the Hosted service  ? Simple,with Singletons:

// in public static IServiceCollection AddCLI(this IServiceCollection serviceCollection)

serviceCollection.AddSingleton<CLIAPIHostedService>();

serviceCollection.AddHostedService<CLIAPIHostedService>(p => p.GetService<CLIAPIHostedService>());

and later on

//in public static IApplicationBuilder UseCLI(this IApplicationBuilder app)

var service = app.ApplicationServices.GetService<CLIAPIHostedService>();
service.app = app;

3.  How to serialize the headers, url, parameters, body and others in a file  – as to pass easy json ?

The idea is that I wrote Json( for sending body data)  in a json file it will become faster complicated. So I was thinking : What other serialized formats I know ?

So I was attracted by YAMLhttps://en.wikipedia.org/wiki/YAML . And there is an implementation https://github.com/aaubry/YamlDotNet . You can find a sample file at https://github.com/ignatandrei/WebAPI2CLI/blob/master/src/TestWebAPISite/cli.txt

4. What to do with errors ?

For example, if some HTTP returns an error message , what can I do  ? The obvious idea is to return on the console the error too…

So I implemented this class to emulate answer

public class ReturnValue_v1
{
public ReturnValue_v1(HttpStatusCode statusCode):this(statusCode,null)
{

}
public ReturnValue_v1(HttpStatusCode statusCode,string result)
{
StatusCode = statusCode;
Result = result;
}
public ICLICommand Command { get; private set; }

public HttpStatusCode StatusCode { get; private set; }
public string Result { get; private set; }

public ReturnValue_v1 FromCommand(ICLICommand cmd)
{
this.Command = cmd;
return this;
}

}

to can return to the console the JSON of this object.

5. How to exit the application ?

This is simple –  Environment.Exit(0);

However , maybe could be a feature to exit if we encounter an error in calling the API ? And if you want to help, https://github.com/ignatandrei/WebAPI2CLI/issues/10

6. How to figure the WebAPI endpoints ?

Simple – with IApiDescriptionGroupCollectionProvider

7. How to help the user to not change the port of adresses every time the .NET Core server change the adress ?

There are so many ways to configure the address of ASP .NET Core  – see https://josephwoodward.co.uk/2017/02/many-different-ways-specifying-host-port-asp-net-core . The CLI.txt file should work the same , no matter the port . So I decided to put just the beginning of the http and then find the right address ( and handle also the case with full URL)

In this file put just –
Host: http://

or

Host: https://

( Assumption : just one http and/or just 1 https when asp.net core will start )

WebAPI2CLI will find the adress and the port comparing

Alternatively, you can put the full URI ( without RelativeRequestUrl ! )

Host: http://localhost:5000/

8. How to make easier for the developer to integrate ?

Create extension – AddCLI and UseCLI .