search

asyncapi / saunter

Saunter is a code-first AsyncAPI documentation generator for dotnet.
https://www.asyncapi.com/
MIT License
204 stars 58 forks source link

Add UI to view documentation #28

Closed m-wild closed 3 years ago

m-wild commented 4 years ago

Similar to Swachbuckle.AspNetCore which provides app.UseSwaggerUI() it would be nice to have an app.UseAsyncApiUI()

tscrypter commented 4 years ago

I'll take this one as well. I was going to attempt to bring in the asyncapi/html-template package and generate the UI dynamically.

m-wild commented 4 years ago

I don't really have a preference for how to do this one. Using the official asyncapi template seems like a great idea! Ideally this all gets packaged up nicely in the NuGet package, and from the users perspective they just add 1 line of code and get a nice UI out of it.

m-wild commented 4 years ago

Not sure how you're getting on with this one, but I had an idea which is kind of a hack/cheating, but would be very simple.

AsyncAPI Playground (https://playground.asyncapi.io/) accepts a query parameter load, which is the URL of an asyncapi document to load. In our case, linking to https://playground.asyncapi.io/?load=http://localhost:5000/asyncapi/asyncapi.json will load the document from our API and render it successfully.

image

If dynamically building the UI turns out to be too complex, this would be an acceptable compromise.

tscrypter commented 4 years ago

I actually started by implementing this approach, so I'll revert my work since that working commit, add some tests and issue a PR. I'll also add some documentation about the dependency on the AsyncAPI Playground.

I'll make the extension method app.UseAsyncApiUI() default to the public AsyncAPI Playground, and also provide a app.UseAsyncApiUI(playgroundBaseUri) for those that want to run their services internally in a firewall and limit external internet access for security reasons.

I wouldn't call it a 'hack' as much as I'd say it's following a microservice architecture to keep the library thin :wink:

tscrypter commented 4 years ago

I'm making progress on this, though I've run into a bit of a headache in terms of serving the css/js for index.html. I'm able to effectively proxy the request to a running instance of playground (I'm actually making an API call to the http://playground/html/generate method call which returns a full html page), and that renders the doc without styles/javascript (subsequent calls from the browser fails).

My first attempt at solving this issue is to try and match on http://localhost:5000/asyncapi/ui/**/* and just proxy those requests to http://playground/**/*. This in my mind would be the ideal so that if the html is updated with new styles, it'll automatically be served.