Создание документации WebAPI в формате swagger json

Я создал WebAPI с использованием .Net 4.5 и хочу документировать этот API с помощью Swagger. Я добавил swagger-ui в мой проект .Net. Теперь, когда я просматриваю.. /swagger -ui/index.html, он успешно открывает любимый магазин api-docs (json) в формате пользовательского интерфейса swagger.

Мой вопрос: как я могу создать такой (swagger) json для моих контроллеров и моделей WebAPI? Поскольку я ввел необходимые резюме/комментарии XML к классам и атрибутам С#.

Я видел, что Swagger.Net и Swashbuckle делают похожие вещи, но я не мог действительно понимаю, как создать файл swagger-json, используя любой из них. Могу быть очень маленькой ошибкой, которую я делаю, но не могу указать.

Пожалуйста, помогите.

Ответ 1

Как указано, /swagger приведет вас к пользовательскому интерфейсу swagger.

Если вы используете Swashbuckle, то /swagger/docs/v1 должен отвезти вас в файл swagger.json - я нашел это с помощью инструментов Chrome Dev.

Изменить: если вы используете Swashbuckle.AspNetCore, то URL-адрес немного отличается - /swagger/v1/swagger.json

Ответ 2

Вам нужно интегрировать Swagger.NET в ваш проект, чтобы в итоге появился следующий контроллер:

public class SwaggerController : ApiController { /* snip */ }

и вы также должны зарегистрировать следующий маршрут:

context.Routes.MapHttpRoute (
name : "Swagger",
routeTemplate: "api/swagger"
defaults: new
{
  controller = "Swagger",
  action = "Get",
});

Предполагая, что вы работаете, вы должны иметь возможность вызвать /api/swagger и получить что-то вроде следующего:

{
  apiVersion: "4.0.0.0",
  swaggerVersion: "2.0",
  basePath: "http://localhost:5555",
  resourcePath: null,
  apis: [
  {
    path: "/api/docs/Values",
    description: "No Documentation Found.",
    operations: [ ]
  },
  {
    path: "/api/docs/Home",
    description: "No Documentation Found.",
    operations: [ ]
  }
]

}

то в SwaggerUI/index.html вы захотите обновить обнаружение url:

<script type="text/javascript">
    $(function () {
        window.swaggerUi = new SwaggerUi({
            discoveryUrl: "http://localhost:5555/api/swagger",
            apiKey:"",
            dom_id:"swagger-ui-container",
            supportHeaderParams: false,
            supportedSubmitMethods: ['get', 'post', 'put']
        });

        window.swaggerUi.load();
    });
</script>

Ответ 3

Вы можете использовать настольное приложение NSwagStudio для загрузки json-документа без запуска проекта api. Предоставляя сборку api.

https://github.com/RSuter/NSwag/wiki/NSwagStudio

Загрузите приложение рабочего стола Windows (NSwagStudio).