Как установить swagger на windows

Обновлено: 03.07.2024

Создание веб-API и интеграция Swagger в Visual Studio 2017

SwaggerЭто стандарт, не имеющий ничего общего с технологиями. Он позволяет обнаруживать REST API и дает возможность любому программному обеспечению идентифицировать функции REST API.

Это важнее, чем кажется: это способ изменить игровые технологии, напримерЯзык описания веб-сервисаодна и та жеТо же, что и WSDL (язык описания веб-служб)。

WSDLВсегда делатьVisual StudioТакие инструменты и IDE могут понимать базовую технологию веб-сервисов и создавать прокси-классы. Эта функция преобразует потребление веб-сервисов в задачи высокого уровня, инкапсулируя все детали протокола.

этоSwaggerВажность: он может выполнять работу, которую WSDL уже проделал для веб-сервисов для REST API, позволяя создавать прокси и использовать веб-API проще.

VS 2017Включая использование протокола Swagger для поддержки создания прокси REST API. Он все еще находится на начальной стадии, и в нем отсутствуют некоторые функции, но это важный шаг на пути к широкому распространению Swagger.

Мы создадим пример, чтобы проиллюстрировать, как мы можем использовать Swagger сVS 2017Проанализировать сильные стороны и недостающие особенности.

Помимо VS 2017, нам также понадобится IIS (Internet Information Server), установленный на машине разработки в качестве примера.

Среда разработки

Вы можете включить IIS как компонент Windows или роль сервера, в зависимости от того, используете ли вы клиентскую операционную систему или роль сервера.

Запустить приложение

Прежде чем мы сможем использовать Swagger, нам понадобится демонстрационное решение с проектом веб-API. Давайте создадим это первоначальное решение, а затем продолжим реализацию Swagger.

1. 1. в«Название решения»В текстовом поле введите“slDemo”, А затем нажмите кнопку «ОК»

   
   

   1. Настройте проект веб-API для использования локальногоIIS
      1. в«Обозреватель решений»Окно, щелкните правой кнопкой мыши“webDemo”Элемент и щелкните«Атрибуты»Пункт меню.
      2. в“webDemo”В правой части окна свойств щелкните“Web”страница

      в"сервер"В поле со списком выберите«Локальный ИИС»

      
      

      В рамках проекта разработан образец элемента управления веб-API, но нам необходимо внести некоторые изменения. Давайте посмотрим на детали существующего контроллера и внесем эти изменения.

      Проанализировать и изменить существующий контроллер API
      в«Обозреватель решений»Окно“webDemo”В проекте откройте«Контроллер»Папку и проверьте существующий контроллер.

      
      

      Измените код ниже“ValuesController”класс. Мы заканчиваемPUTУправляйте списком и сохраните его в области памяти приложения.

      namespace webDemo.Controllers
      public class ValuesController : ApiController

      
      public IEnumerable<string> Get()
      return lista;
      >

      
      public string Get(int id)

      
      public void Post([FromBody]string value)
      

      
      public void Put(int id, [FromBody]string value)
      lista[id] = value;
      >

      
      public void Delete(int id)

      1. Запустите приложение и проанализируйте результаты
         1. Щелкните на панели инструментов"Начало"Кнопка для запуска приложения

         На только что открытой веб-странице щелкните значок“API”ссылка. Вы заметите, что операции API - это в основном одна с двумяПОЛУЧИТЬCRUD, одинPOST，PUTс участиемDELETE

         
         

         
         

         Включите Swagger в наш проект

         Попрактикуемся в использовании шаг за шагомSwashBuckleЧтобы реализовать Swagger:

         1. Включить в проект веб-APISwashBuckleПакет слепков
            1. В "Обозреватель решений "Окно, щелкните правой кнопкой мыши“webDemo”Элемент и щелкните«Управление пакетами nuget»Пункт меню.
            2. в«Диспетчер пакетов Nuget»Окно, выберите"Просматривать"
            3. в«Диспетчер пакетов Nuget»В текстовом поле в окне введите“SwashBuckle”。

            
            

            1. 1. в«Диспетчер пакетов Nuget»В правой части окна нажмите"установка"Кнопка.
               2. в«Посмотреть изменения»В открывшемся окне нажмите кнопку «ОК».
               3. в«Принятие лицензии»Окно, щелкните"Я принимаю Я согласен"Кнопка.
               4. неисправность«Диспетчер пакетов Nuget»окно
               1. в«Обозреватель решений»Окно, щелкните правой кнопкой мыши“webDemo”Элемент и щелкните«Атрибуты»Пункт меню.
               2. в“webDemo”Окно, щелкните"Построить"страница

               в'webDemo'В окне"Вывод"Ниже нажмите«Файл XML-документа»Флажок. В текстовом поле справа вы увидите путь“bin \ webDemo.xml”。

               
               

               /// Retrieves the list of values

               public IEnumerable<string> Get()

               /// Retrieves one value from the list of values

               /// <param name=<em>"id"</em>>The id of the item to be retrieved</param>

               public string Get(int id)

               /// Insert a new value in the list

               public void Post([FromBody]string value)

               /// Change a single value in the list

               /// <param name=<em>"id"</em>>The id of the value to be changed</param>

               public void Put(int id, [FromBody]string value)

               /// Delete an item from the list

               public void Delete(int id)

               
               

               protected static string GetXmlCommentsPath()

               На странице документации Swagger щелкните"значение",Имя контроллера.

               
               

               Открыть с помощью блокнотаv1.jsonфайл. Формат файла будет не очень хорошим, но его содержимое представляет собой описание веб-API, как показано на рисунке ниже. При желании вы можете открыть файл в Visual Studio, чтобы увидеть правильную версию формата файла.

               
               

               Создать клиентский проект

               Пришло время создать клиента для использования нашего веб-API и объяснить, как это потребление будет намного проще.

               в«Обозреватель решений»Окно, щелкните правой кнопкой мыши“winClient”Пункт, щелкните"Добавить в" - > «Клиент REST API»Пункт меню.

               
               

               In the ‘Client Namespace’ textbox, type ‘SvcRest’ and click the ‘Ok’ button.

               
               

               It seems that nothing happened. Inside ‘Web Publish Activity’ window you will be able to see what happened and an error message: ‘Found operation object with duplicate OperationId ‘Values_Get’. OperationId must be unique among all operations described in the API’.

               The client tool doesn’t support a REST API with operation overload, and our demo API has two GET methods. We need to resolve this problem before we proceed.

               Support for operation overload

               Отсутствие поддержки перегрузки операций является большим недостатком, потому что даже демонстрационное приложение веб-API, которое вы, возможно, заметили, использует перегрузку операций, которая имеет дваGETЭксплуатация, с параметрами и без.

               Есть два возможных решения:

               • Измените название операции, чтобы избежать перегрузки
               • Реализуйте фильтр операций, который может перехватывать создание файлов JSON, чтобы избежать перегрузки в файлах JSON.

               Пошагово реализуем фильтр операций:

               в"имя"В текстовом поле введите“libTools”, А затем нажмите кнопку «ОК»

               
               

               в«Добавить новый элемент»В окне"имя"Введите текстовое поле“MultipleOperationsWithSameVerbFilter.cs”。

               
               

               public class MultipleOperationsWithSameVerbFilter : IOperationFilter

               public void Apply(

               if (operation.parameters != null)

               foreach (var parm in operation.parameters)

               1. в«Обозреватель решений»Окно, щелкните правой кнопкой мыши“webDemo”Пункт, щелкните"Добавить в" - > "Справка"Пункт контекстного меню
               2. в«Справочник-менеджер»В левой части окна выберите"проект" - > "решение"вещь

               в«Справочник-менеджер»В правой части окна выберите'libTools'Вне коробки и нажмите кнопку «ОК»

               
               

               Добавьте следующие строки кода:

               в«Обозреватель решений»Окно, щелкните решение правой кнопкой мыши и выберите«Восстановить решение»Пункт меню

               
               

               1. Повторите шаг 2 создания прокси-сервера клиента, на этот раз он будет работать.

               Используйте прокси в клиентском приложении

               Теперь, когда прокси веб-API встроен в клиентский проект, пришло время использовать его для доступа к веб-API. Однако прокси-серверу требуется дополнительный класс для управления аутентификацией. Еще одним недостатком этой функции является то, что она не поддерживает анонимную аутентификацию, но мы можем решить эту проблему, быстро решив ее.

               Swagger — это технология, которая позволяет документировать REST-сервисы. Swagger поддерживает множество языков программирования и фреймворков. Также Swagger предоставляет UI для просмотра документации.

               
               

               В данной статье я расскажу как подключить Swagger к Maven проекту, в котором реализованы REST-сервисы с помощью спецификации JAX-RS — RESTEasy. В статье будет расписано подключение Swagger к проекту, использование документирования REST-сервисов с помощью аннотаций, описание визуализации документации через Web UI.

               Подключение Swagger к проекту

               Подключение Maven зависимостей

               Для начала мы должны добавить в проект Maven зависимость Swagger’а. Так как мы будет подключать Swagger к RESTEasy, то добавим соответствующую зависимость.

               На момент написания мануала актуальной версией является 1.5.6.

               Нужно учесть, что у Swagger есть legacy Maven репозиторий. У lagecy репозитория groupId=com.wordnik. Нужно это учесть и не перепутать зависимости!

               Более подробно можно прочитать тут.

               Настройка проекта

               Далее нам необходимо подключить в проект необходимых слушателей (listeners), чтобы Swagger мог автоматически определять аннотации и генерировать документацию.

               Мы производили настройку с помощью потомка класса javax.ws.rs.core.Application.
               Настройка будет выглядеть так:

               Более подробно о других методах подключения можно почитать тут.

               Настройка Swagger

               Далее необходимо установить настройки самого Swagger. Мы это сделали в конструкторе того же наследника класса Application.

               Более подробно о других методах настройки можно прочитать тут.

               Аннотации

               Для начала я опишу аннотации, которые являются обязательными для правильного документирования и корректного отображения REST-сервисов на Swagger-UI.

               Для того, чтобы swagger определил, что в классе находятся REST-сервисы, этот класс должен быть помечен аннотацией @Api. В параметрах данной аннотации можно указать название раздела, в котором будут находится REST’ы в UI, и указать описание данного раздела.
               Например:

               @ApiOperation

               Аннотацию @ApiOperation необходимо указывать над методом REST-сервиса. Также в её параметрах можно указать описание сервиса.

               Другие аннотации

               Для явного указания хидеров, которые являются обязательными для конкретного сервиса можно использовать аннотацию @ApiImplicitParam

               Для явного указания объекта ответа можно использовать аннотацию @ApiResponse. Это будет полезно, если в качестве ответа от сервера REST возвращает объект Responce.

               Более подробную информацию обо всех аннотациях можно найти тут.

               WEB UI

               Чтобы установить url по умолчанию необходимо отредактировать исходный код файла index.html

               После чего мы увидим документацию наших REST-сервисов. Делать запросы к REST-сервисам можно прямо из UI.

               В случае если Swagger выдаст ошибку can`t fetch нужно будет производить настройку CORS headers в сервере, на котором задеплоено наше приложение, нам нужно добавить header Access-Control-Allow-Origin:*

               Пример отображения REST-сервисов на UI:

               
               

               Список REST сервисов на Web-UI:

               
               

               Форма детальной информации о REST-сервисе и возможности отправки запроса.

               Swashbuckle.AspNetCore.Swagger: объектная модель Swagger и ПО промежуточного слоя для предоставления объектов SwaggerDocument как конечных точек JSON.

               Swashbuckle.AspNetCore.SwaggerGen: генератор Swagger, создающий объекты SwaggerDocument непосредственно из ваших маршрутов, контроллеров и моделей. Как правило, он комбинируется с ПО промежуточного слоя конечной точки Swagger и за счет этого предоставляет Swagger JSON автоматически.

               Swashbuckle.AspNetCore.SwaggerUI: встроенная версия средства пользовательского интерфейса Swagger. Она интерпретирует Swagger JSON и обеспечивает удобную настраиваемую среду для описания функциональности веб-API. Включает встроенные окружения тестов для открытых методов.

               Установка пакета

               Swashbuckle можно добавить одним из описанных ниже способов.

               В окне Консоль диспетчера пакетов

               Последовательно выберите Представление > Другие окна>Диспетчер пакетов консоли.

               Перейдите в каталог, в котором существует файл .csproj.

               Выполните следующую команду:

               В диалоговом окне Управление пакетами NuGet

               Во встроенном терминале выполните следующую команду.

               Выполните следующую команду:

               Добавление и настройка ПО промежуточного слоя Swagger

               Добавьте генератор Swagger в коллекцию служб в файле Program.cs:

               В том же файле Program.cs разрешите использовать ПО промежуточного слоя для обслуживания созданного документа JSON и пользовательского интерфейса Swagger:

               Приведенный выше код добавляет ПО промежуточного слоя Swagger только в том случае, если выбрана текущая среда Development (Разработка). Вызов метода UseSwaggerUI включает ПО промежуточного слоя для статических файлов.

               По умолчанию Swashbuckle генерирует и предоставляет JSON-файл Swagger в версии 3.0 спецификации, которая официально называется OpenAPI. Чтобы обеспечить обратную совместимость, можно предоставлять JSON-файл в формате версии 2.0. Формат 2.0 необходим для интеграции с такими продуктами, как Microsoft Power Apps и Microsoft Flow, которые сейчас поддерживают спецификацию OpenAPI версии 2.0. Чтобы перейти на формат 2.0, задайте свойство SerializeAsV2 в файле Program.cs:

               Настройка и расширение

               Swagger предоставляет параметры для документирования объектной модели и настройки пользовательского интерфейса в соответствии с вашим фирменным стилем.

               Данные и описание API

               Действие настройки, передаваемое в метод AddSwaggerGen , можно использовать для добавления сведений об авторе, лицензии и описании.

               В файле Program.cs импортируйте следующие пространства имен, чтобы использовать класс OpenApiInfo :

               С помощью класса OpenApiInfo измените информацию, которая отображается в пользовательском интерфейсе:

               Пользовательский интерфейс Swagger отображает сведения о версии:

               
               

               XML-комментарии

               XML-комментарии можно включить следующим образом.

               Вручную добавьте выделенные строки в файл .csproj:

               Вручную добавьте выделенные строки в файл .csproj:

               Настройте Swagger на использование XML-файла, который создается с помощью приведенных выше инструкций. В Linux и других операционных системах, отличных от Windows, имена и пути файлов могут быть чувствительны к регистру. Например, файл ToDoApi.XML допустим в Windows, но не в CentOS.

               Включение в действие комментариев с тройной косой чертой улучшает пользовательский интерфейс Swagger, так как позволяет добавить описание к заголовку раздела. Добавьте элемент <summary> над действием Delete :

               Пользовательский интерфейс Swagger отображает внутренний текст элемента <summary> в приведенном выше коде:

               
               

               Пользовательский интерфейс определяется созданной схемой JSON:

               Добавьте элемент <remarks> в документацию по методу действия Create . Он дополняет сведения, указанные в элементе <summary> , и предоставляет более надежный пользовательский интерфейс Swagger. Содержимое элемента <remarks> может включать текст, JSON или XML.

               Обратите внимание, как эти дополнительные комментарии улучшают пользовательский интерфейс:

               
               

               Заметки к данным

               Добавьте атрибут [Required] к свойству Name класса TodoItem .

               Наличие этого атрибута изменяет поведение пользовательского интерфейса и схему базового JSON.

               Добавьте к контроллеру API атрибут [Produces("application/json")] . Он позволяет объявить, что действия контроллера поддерживают тип содержимого ответа application/json:

               В раскрывающемся списке Тип носителя этот тип содержимого выбирается по умолчанию для операций контроллера GET.

               
               

               Чем больше заметок к данным используется в веб-API, тем более содержательными и полезными становятся пользовательский интерфейс и страницы справки по API.

               Соглашения можно использовать в качестве альтернативы явному добавлению элемента [ProducesResponseType] к отдельным действиям. Для получения дополнительной информации см. Использование соглашений веб-API.

               Для поддержки оформления с помощью [ProducesResponseType] пакет Swashbuckle.AspNetCore.Annotations содержит расширения, которые позволяют включить и обогатить метаданные отклика, схемы и параметра.

               Настройка пользовательского интерфейса

               Стандартный пользовательский интерфейс отличается функциональностью и презентабельностью. Но на страницах документации по API должна быть представлена ваша фирменная символика или тема. Для оформления компонентов Swashbuckle в фирменном стиле необходимо добавить ресурсы для обслуживания статических файлов, а затем построить структуру папок для их размещения.

               Включите ПО промежуточного слоя для статических файлов:

               Чтобы вставить таблицы стилей CSS, добавьте их в папку wwwroot проекта и укажите относительный путь в параметрах ПО промежуточного слоя:

               Дополнительные ресурсы

               Swashbuckle включает три основных компонента.

               Swashbuckle.AspNetCore.Swagger: объектная модель Swagger и ПО промежуточного слоя для предоставления объектов SwaggerDocument как конечных точек JSON.

               Swashbuckle.AspNetCore.SwaggerGen: генератор Swagger, создающий объекты SwaggerDocument непосредственно из ваших маршрутов, контроллеров и моделей. Как правило, он комбинируется с ПО промежуточного слоя конечной точки Swagger и за счет этого предоставляет Swagger JSON автоматически.

               Swashbuckle.AspNetCore.SwaggerUI: встроенная версия средства пользовательского интерфейса Swagger. Она интерпретирует Swagger JSON и обеспечивает удобную настраиваемую среду для описания функциональности веб-API. Включает встроенные окружения тестов для открытых методов.

               Установка пакета

               Swashbuckle можно добавить одним из описанных ниже способов.

               В окне Консоль диспетчера пакетов

               Последовательно выберите Представление > Другие окна>Диспетчер пакетов консоли.

               Перейдите в каталог, в котором существует файл TodoApi.csproj

               Выполните следующую команду:

               В диалоговом окне Управление пакетами NuGet

               Во встроенном терминале выполните следующую команду.

               Выполните следующую команду:

               Добавление и настройка ПО промежуточного слоя Swagger

               Добавьте генератор Swagger в коллекцию служб в методе Startup.ConfigureServices :

               В методе Startup.Configure включите ПО промежуточного слоя для обслуживания созданного документа JSON и пользовательского интерфейса Swagger:

               Swashbuckle обнаруживает маршруты и конечные точки на основе пространства имен Microsoft.AspNetCore.Mvc.ApiExplorer MVC. Если проект вызывает AddMvc, маршруты и конечные точки обнаруживаются автоматически. При вызове AddMvcCore метод AddApiExplorer должен быть вызван явным образом. Дополнительные сведения см. в разделе Swashbuckle, ApiExplorer, and Routing (Swashbuckle, ApiExplorer и маршрутизация).

               По умолчанию Swashbuckle генерирует и предоставляет JSON-файл Swagger в версии 3.0 спецификации, которая официально называется OpenAPI. Чтобы обеспечить обратную совместимость, можно предоставлять JSON-файл в формате версии 2.0. Формат 2.0 необходим для интеграции с такими продуктами, как Microsoft Power Apps и Microsoft Flow, которые сейчас поддерживают спецификацию OpenAPI версии 2.0. Чтобы перейти на формат 2.0, задайте свойство SerializeAsV2 в Startup.Configure следующим образом:

               Настройка и расширение

               Swagger предоставляет параметры для документирования объектной модели и настройки пользовательского интерфейса в соответствии с вашим фирменным стилем.

               В классе Startup добавьте следующие пространства имен:

               Данные и описание API

               Действие по настройке, передаваемое в метод AddSwaggerGen , можно использовать для добавления таких сведений, как автор, лицензия и описание:

               В классе Startup импортируйте следующие пространства имен для использования в классе OpenApiInfo :

               С помощью класса OpenApiInfo измените информацию, которая отображается в пользовательском интерфейсе:

               Пользовательский интерфейс Swagger отображает сведения о версии:

               
               

               XML-комментарии

               XML-комментарии можно включить следующим образом.

               Вручную добавьте выделенные строки в файл .csproj:

               Вручную добавьте выделенные строки в файл .csproj:

               Настройте Swagger на использование XML-файла, который создается с помощью приведенных выше инструкций. В Linux и других операционных системах, отличных от Windows, имена и пути файлов могут быть чувствительны к регистру. Например, файл ToDoApi.XML допустим в Windows, но не в CentOS.

               Включение в действие комментариев с тройной косой чертой улучшает пользовательский интерфейс Swagger, так как позволяет добавить описание к заголовку раздела. Добавьте элемент <summary> над действием Delete :

               Пользовательский интерфейс Swagger отображает внутренний текст элемента <summary> в приведенном выше коде:

               
               

               Пользовательский интерфейс определяется созданной схемой JSON:

               Добавьте элемент <remarks> в документацию по методу действия Create . Он дополняет сведения, указанные в элементе <summary> , и предоставляет более надежный пользовательский интерфейс Swagger. Содержимое элемента <remarks> может включать текст, JSON или XML.

               Обратите внимание, как эти дополнительные комментарии улучшают пользовательский интерфейс:

               
               

               Заметки к данным

               Добавьте атрибут [Required] к свойству Name класса TodoItem .

               Наличие этого атрибута изменяет поведение пользовательского интерфейса и схему базового JSON.

               Добавьте к контроллеру API атрибут [Produces("application/json")] . Он позволяет объявить, что действия контроллера поддерживают тип содержимого ответа application/json:

               В раскрывающемся списке Тип содержимого ответа этот тип содержимого выбирается по умолчанию для операций контроллера GET.

               
               

               Чем больше заметок к данным используется в веб-API, тем более содержательными и полезными становятся пользовательский интерфейс и страницы справки по API.

               Для поддержки оформления с помощью [ProducesResponseType] пакет Swashbuckle.AspNetCore.Annotations содержит расширения, которые позволяют включить и обогатить метаданные отклика, схемы и параметра.

               Настройка пользовательского интерфейса

               Стандартный пользовательский интерфейс отличается функциональностью и презентабельностью. Но на страницах документации по API должна быть представлена ваша фирменная символика или тема. Для оформления компонентов Swashbuckle в фирменном стиле необходимо добавить ресурсы для обслуживания статических файлов, а затем построить структуру папок для их размещения.

               Включите ПО промежуточного слоя для статических файлов:

               Чтобы вставить таблицы стилей CSS, добавьте их в папку wwwroot проекта и укажите относительный путь в параметрах ПО промежуточного слоя:

               В данной статья я хотел бы показать решение для создания Swagger спецификаций на основании конфигураций 1С.

               Что же такое Swagger спецификация? Небольшая выдержка с Wiki:

               The OpenAPI Specification (изначально известная как Swagger Specification)— формализованная спецификация и экосистема множества инструментов, предоставляющая интерфейс между front-end системами, кодом библиотек низкого уровня и коммерческими решениями в виде API. Вместе с тем, спецификация построена таким образом, что не зависит от языков программирования, и удобна в использовании как человеком, так и машиной.

               Относительно назначения, OpenAPI рассматривается как универсальный интерфейс для пользователей (клиентов) по взаимодействию с сервисами (серверами). Если спроектирована спецификация для некоторого сервиса, то на её основании можно генерировать исходный код для библиотек клиентских приложений, текстовую документацию для пользователей, варианты тестирования и др. Для этих действий имеется большой набор инструментов для различных языков программирования и платформ.

               
               

               Это позволит публиковать документацию сервисов 1С в общепринятом, стандартизованном формате, общаясь с внешними командами общепринятом в среде профессионалов языке спецификаций API, не дополняя общение постыдными фразами вида "ой, у нас 1С, у нас нет Swagger, наш программист сейчас напишет все в Ворде". Swagger - это документация которая не врет и не отстает от основного кода, поскольку является его продолжением и создается автоматически. Никаких больше "документаций сервиса в Word!"

               Что бы получить желаемый результат, мной была создана OneScript библиотека - swagger, которая реализует формирование второй редакции OpenAPI спецификации.

               Простой пример

               Постановка задачи

               Возникла потребность создать API управления доступом в систему 1С. Необходимые возможности:

               • Получить список всех пользователей
               • Получить все свойства пользователя
               • Изменить все свойства пользователя
               • Изменить одно свойство пользователя
               • Создать нового пользователя
               • Удалить существующего пользователя

               Подготовка метаданных

               • Имя UserAPI(имя сервиса)
               • Синоним API управления доступом(описание сервиса)
               • Комментарий 1.0(версия сервиса)

               
               

               Создадим наборы шаблонов URL:

               
               

               
               

               
               

               Болванка нашего сервиса готова. Выгрузим конфигурацию в файлы, используя каталог D:\ПримерКонфигурация\. Далее займемся установкой и настройкой необходимых инструментов.

               Инструменты

               Установим или обновим OneScript до актуальной версии (на момент написания статьи 1.1.1). Далее установим библиотеку swagger:

               Так же потребуется наличие IIS на своей машине или ином сервере. Но все примеры ниже будут в рамках localhost.

               Скачаем содержимое папки dist из официального репозитория Swagger-UI.

               Скачаем содержимое папки simple-ui из репозитория библиотеки swagger.

               Настройка Simple-UI

               Развертывание spec-admin

               В IIS добавим новое приложение:

               
               

               Проверим готовность сервиса обычным GET запросом на:

               В теле ответа от сервиса мы должны получить "[]".

               Развертывание Swagger-UI

               В IIS добавим новый виртуальный каталог:

               
               

               Проверим в браузере:

               
               

               Далее заменим файл index.html в каталоге onec-swagger-ui на аналогичный файл из Simple-UI.

               Завершающим этапом откроем в любом редакторе новый файл index.html и заменим в строчке:

               "localhost" на адрес вашего IIS сервера:

               Первый результат

               Из репозитория библиотеки swagger скачаем скрипт upload.os. У нас уже есть выгруженная в файлы конфигурация D:\ПримерКонфигурация\.

               Открываем терминал и выполним следующую команду:

               
               

               Делаем красиво

               Рассмотрим более подробное описание метода PUT /user/ :

               
               

               Как мы видим, библиотекой swagger в сформированной спецификации явно описан параметр userID с пометкой входящий и расположением в пути запроса. Так же по умолчанию подставляется единственный код ответа сервиса - 200 (см. стандарт RFC7231) и тип данных в теле ответа считается обычным текстом (см. стандарт RFC6838).

               На данный момент сформированная спецификация основана только на метаданных конфигурации. Но мы ее сделаем еще информативнее.

               Комментарий по стандарту

               В стандартах разработки на ИТС у нас есть такой замечательный документ. Он достаточно подробно показывает как нам правильно описывать свои процедуры и функции.

               Воспользуемся данным стандартом, и добавим подробное описание функций в модуле сервиса:

               Обновим спецификацию, проверяем что в каждый метод добавилось описание:

               
               

               Следующим шагом опишем входящие параметры, которые явно заданы в пути (шаблон /user/ ):

               Обновим спецификацию, проверяем описание параметра userID:

               
               

               Так как в логике работы некоторых методов подразумевается получение данных из тела запроса или в строке самого запроса, добавим в соответствующие комментарии:

               • для методов PUT и POST добавим описание параметра body(ключ-слово библиотеки swagger)
               • для метода PATCH добавим описание параметров property и value(напомню, логика обработки данного метода подразумевает изменение конкретного свойства)

               Обновим спецификацию, проверяем описание параметра body:

               
               

               а так же для метода PATCH:

               
               

               Комментарий не по стандарту

               Рассмотрим ситуацию, что по переданному userID пользователь в системе не был найден. Тогда наш сервис должен вернуть код ответа 404. А если в процессе изменения свойства пользователя в базе 1С произошла ошибка (все же пользуются транзакцией с попыткой) то вернем код ответа 500.

               где XXX - код ответа по стандарту RFC7231.

               Дописываем изменения в модуле:

               Обновим спецификацию, проверяем блоки Responses:

               
               

               Заключение

               На данный момент, библиотека swagger выпущена как минимально жизнеспособный продукт (MVP). В планах стоят следующие задачи:

               1. Добавить поддержку формирования спецификации для конфигурации в формате проекта EDT.
               2. Найти приемлемый способ описания схемы объектов API в конфигурации 1С. Пока я вижу этот момент как описание в комментарии, примерно следующим образом:

               что будет соответствовать объекту в json:

               и в спецификации будет описание в схеме:

               1. Научиться связывать спецификации с настройками публикации тестовых база и попробовать автотесты.

               Буду рад любой конструктивной критике и предложениям.

               Благодарности

               Особую благодарность выражаю Овсянкину Андрею за помощь в подготовке данной статьи, а сообществу OneScript за отличный продукт и прекрасное комьюнити.

               Читайте также:

                 
               • Не устанавливаются дополнительные компоненты windows 10
                 
               • Поддерживает ли windows 2000 ntfs
                 
               • Помощник по совместимости невозможно запустить это приложение на данном устройстве windows 10
                 
               • Код ошибки 85050025 windows phone nokia lumia
                 
               • Ubuntu не видит сетевую карту