search

dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
3.94k stars 839 forks source link

[Bug] Swagger basePath is not rendered in the generated html #10009

Open daniecas opened 3 weeks ago

daniecas commented 3 weeks ago

Describe the bug Even if you set basePath in the Swagger file the path is not rendered in the Html file generated.

To Reproduce Steps to reproduce the behavior:

  1. clone https://github.com/docascode/docfx-seed/tree/master
  2. the following file contain "basePath": "/myorganization" --> https://github.com/docascode/docfx-seed/blob/master/restapi/contacts_swagger2.json)
  3. the result is no text with "/myorganization" in the html generated --> https://docascode.github.io/docfx-seed/restapi/contacts.html

Expected behavior Without the base path the api path showed is wrong , so I think it's important to show the basePath on the top of the html generated

Context:

Additional context I tried it with 2 different template (modern and default).

filzrev commented 3 weeks ago

When using Swagger UI. basePath setting is rendered as following text.

Currently docfx don't render basePath information and RestApiRootItemViewModel don't hold this information. So it can't render this information by docfx template customization only.

I thought, it requires following tasks to support basePath rendering.

  1. Add BaseUrl property to RestApiRootItemViewModel.
  2. Set BaseUrl property at SwaggerModelConverter.FromSwaggerModel.
  3. Modify following files to render baseUrl information. 3.1. default/partials/rest.tmpl.partial 3.2. `statictoc/partials/rest.tmpl.partial
daniecas commented 1 week ago

Thank you @filzrev, I'm working on it, I'm going to create a PR for next week :-)