Hello all,
I am currently trying to use Swagger a JSON spec to describe your API: http://swagger.io

There is a .NET implementation of this called SwashBuckle that I heard about via Scott Hanselman, that will automatically generate this specification for you & give you a test UI like this one here http://petstore.swagger.io that gives us an easy way to test our APIs and give it as documentation to a front end developer implementing them.

https://github.com/domaindrivendev/Swashbuckle
http://bitoftech.net/2014/08/25/asp-net-web-api-documentation-using-swagger/

I installed the NuGet package SwashBuckle into my Umbraco Web Application: http://www.nuget.org/packages/Swashbuckle/5.0.4

By doing this I am able to see a list of all the APIs (my custom ones and the Umbraco ones too) when I browse to http://mysite.co.uk/swagger/

I thought great this just simply works, however I have run into a problem/conflict with Umbraco when Swagger is installed.

When I try to edit the hostnames of a node and click save I get an unusual behaviour of part of the Swagger UI injected into the dialog at the very top and the hostname change is not saved/amended.

On further investigation & digging around to see what is going on, the dialog is an old ASPX webforms page that lives here http://mysite.co.uk/umbraco/dialogs/assignDomain2.aspx?id=4985&rnd=635634767579885245

In this page I can see some inline JavaScript variables when I view the source of this page:

<script type="text/javascript">
    (function ($) {
        $(document).ready(function () {
            var dialog = new Umbraco.Dialogs.AssignDomain2({
                nodeId: 4985,
                restServiceLocation: '/swagger?action=ListDomains&controller=DomainsApi/',
                invalidDomain: 'Invalid domain format.',
                duplicateDomain: 'Domain has already been assigned.',
                languages: [{ "Id": 1, "Code": "en-US" },{ "Id": 2, "Code": "de-CH" },{ "Id": 3, "Code": "fr-CH" },{ "Id": 4, "Code": "en-GB" }]
,language: undefined,domains: [{ "Name": "mysite.local", "Lang": "4" },{ "Name": "dev.mysite.co.uk", "Lang": "4" }]

            });
        dialog.init();
    });
    })(jQuery);
</script>

The line that looks to be a problem is the variable called restServiceLocation that has the following URL: '/swagger?action=ListDomains&controller=DomainsApi/'

If I disable Swagger & re-compare this variable I have the following: '/umbraco/BackOffice/Api/DomainsApi/'

So I started to try & debug the issue by browsing the Umbraco source code. The aspx page has a method that it calls in the CodeBehind called GetRestServicePath()
https://github.com/umbraco/Umbraco-CMS/blob/4974e2a2ce40aeb3e97e5cb428b22867ce8aaeaa/src/Umbraco.Web.UI/umbraco/dialogs/AssignDomain2.aspx#L16

If I look at what this method does in the code behind of the page which calls an extension method called GetUmbracoApiService it is this method that seems to be returning a different result when Swagger is enabled.

https://github.com/umbraco/Umbraco-CMS/blob/ded1def8e2e7ea1a4fd0f849cc7a3f1f97cd8242/src/Umbraco.Web/umbraco.presentation/umbraco/dialogs/AssignDomain2.aspx.cs#L78

So can anyone offer me any advice on how to get Swagger & Umbraco to play nicely together ie: mainly this GetUmbracoApiService method that would be fantastic.

Cheers,
Warren :-)