I was wondering if there a simple way how to convert XML comments (triple forward slashes) to YAML. I checked the Visual Studio Marketplace and Nuget Gallery and did not find anything relevant.
To give you a high level picture I am developing a set of APIs on Visual Studio and then publishing them on Azure Functions. On Azure Funtions I have enabled OpenAPI definition which generates a YAML file. The problem is the YAML is quite basic and moreover I would like to update the YAML on Azure whenever I re-publish my APIs. Is there an automated how to achieve this? Thanks in advance.
I think the tool you're looking for is Swashbuckle.
Seamlessly adds a Swagger to WebApi projects! Combines ApiExplorer and Swagger/swagger-ui to provide a rich discovery, documentation and playground experience to your API consumers.
In addition to its Swagger generator, Swashbuckle also contains an embedded version of swagger-ui which it will automatically serve up once Swashbuckle is installed. This means you can complement your API with a slick discovery UI to assist consumers with their integration efforts. Best of all, it requires minimal coding and maintenance, allowing you to focus on building an awesome API!
Here's the original version. There's also a Swashbuckle.AspNetCore which you should probably take a look at first, since...
With the introduction of ASP.NET Core, I've now shifted my focus to the Core-specific project - Swashbuckle.AspNetCore.
Related
This is a "Veracity Platform" question - which I guess has a fairly small audience.
I'm using the veracity platform's application generator (based on Yeoman) to generate a sample application for .net core 2.x, using node.js.
yo #veracity/veracity:netcore-webapp
This creates a good basic .net core 2.x MVC project. Is there a way to further specify that I want to additionally include the "React/Redux" project template, like I would when creating a project in Visual Studio? That way the client app and the front-end webpack stack get started for me, which is nice.
Thanks in advance for any suggestions.
We do not have these configurations included in the generator yet. Uservoice will be added to Developer.veracity.com soon, but for now you may forward such feature requests also in the github project of the generator. Open an issue, and I will see when we can get it in to the backlog.
https://github.com/veracity/generator-veracity
Brede Børhaug - Manager Veracity for Developers
I have been working with the HL7 FHIR .NET API reference implementation - utilizing the existing resource models embedded in the library. Now, I am trying to use the Forge tool to modify the resources (contraints/extensions) to suit my requirements.
I noticed that the HL7 publishing mechanism does not generate C# models from DSTU 2 onwards and was wondering - what is the best way of converting profiles created using Forge into C# resource classes such that they may be included into the HL7.Fhir.Model assembly that is part of the reference implementation.
The generation of the models not being part of the official build is correct.
This has now moved to https://github.com/ewoutkramer/fhir-net-api where the rest of the API is maintained more easily.
It is done using T4 templates on the output from the official builds.
There is a simple process for updating the models with the new versions of the spec, and we keep it fresh as people need it, and for each connectathon we publish a new build in NuGet and have a branch of the code in GitHub.
(Its a powershell script that downloads all the latest build outputs and puts them in the appropriate folders, then you need to run the t4 templates in Visual Studio)
Such as this one for the May Connectathon in Montreal
https://github.com/ewoutkramer/fhir-net-api/tree/ft-connectathon-may2016
This is able to be done yourself with a little assistance.
As for generating code for a profile, we haven't done that as yet, but will theoretically be possible.
Don't know that I'd advise this at the moment while the profiles are in so much development and change.
I just got started working on ASP.NET 5. I want to have a help page for my methods, I have seen few examples for creating help pages but most of them are MVC specific. I have gone through Microsoft.AspNet.WebApi.HelpPage package, it creates an Area for help page but I am not using MVC pattern.
Any suggestions how can I create help page other than this area approach?
I would suggest looking at Swagger and SwaggerUI. Swagger is an open standard, using JSON to document an API, used by the likes of PayPal and Microsoft (check out Logic apps in the azure portal).
There are some open source implementations for .Net (both of which I have used), which will self document your API, just by adding the NuGet packages to your project and a little bit of configuration:
https://github.com/domaindrivendev/Swashbuckle
https://github.com/domaindrivendev/Ahoy
Swashbuckle is the original project and Ahoy is the new version targeting ASPNET5. When downloading the package from NuGet you will still get Swashbuckle, just make sure you tick "include pre-release", and if you need any documentation look at the original GitHub project.
SwaggerUI (which is also included in Swashbuckle) adds an interface which you can use to navigate and test your API, by default this is available from "/swagger/ui" when your project is running.
Here is a sample repo in GitHub I put together showing how it can be used: https://github.com/mattridgway/ASPNET5-SwaggerUI
We have a very old application dating back to ASP era which we are gradually refactoring to ASP.NET + VB.NET codebase.
It contains a lots of files with the below types:
aspx, asmx, ascx, vb, js (JavaScript), html, vbs (VBScript).
The backend database is SQL Server 2005 with lots of sprocs.
We would like to create a code documentation automatically generated from the comments in the code files. I liked Doxygen very much but seems like it does not support the above technologies. Can you please suggest some document generator tools, preferably a single tool or a group of tools?
Thanks a lot.
Ajit.
You can take a look at Microsoft's Sandcastle tool. I've used it many times, and it generates documentation based on the comments provided in your .NET code. If I remember correctly, it can also generate documentation for JavaScript libraries.
There are some out there:
SandCastle
NDOC
i've used SandCastle and it works too good if you have xml comments in your code.
You first enable xml documentation in your project by setting it in Project Properties -> Compile -> Generate XML Documentation.
Once done you may have to set treat warnings as errors, so that the studio can point out to you where and all the XML comments are missing.
To add an XML Comment, you place your cursor before a class definition or a function definition and type
///
This will automatically generate xml tags for documentation and then once you are done, you can import the project and start to build the documentation.
The good part is, if you have documented your classes well, when you use those functions in your application upon mouse over you can find the description which you wrote, much like how intellisense documentation works.
Let me know if you run into any other issues.
My last suggestion, make a hello world project and xml document it and get used to sandcastle with it.
I use HttpWebRequests pretty extensively - I've found that the Visual Studio Web Test classes (i.e. WebTestRequest and WebTestResponse etc) offer a lot of really nice methods that i'd love to start using.
But I can't seem to find a way to use these classes outside of the Visual Studio's testing framework. Has anyone done this?
Will,
WebTestRequest and WebTestResponse aren't designed to be used like HttpWebRequest and HttpWebResponse. They're mostly containers for passing various request and response data into and out of the web/load test engine in Visual Studio or MSTest.
I wrote both of the classes and even I find myself wishing I could use them for other purposes :) I've definitely had to reinvent similar querystring parameter parsing logic for other projects since then.
Josh