Как вставить незначительные настройки в Swagger внутри его разметки? - PullRequest
Новая
       134

Как вставить незначительные настройки в Swagger внутри его разметки?

0 голосов
/ 12 октября 2018

У меня есть проект .NET Core, задокументированный Swagger 3 (Swashbuckle.AspNetCore.SwaggerGen 3.0.0 и Swashbuckle.AspNetCore.SwaggerUi 3.0.0).Моя цель - добавить собственный тег прямо под DIV с классом title (т.е. под именем сервиса, но над конечными точками).

Когда я исследую разметку, я вижу, что есть DIV скласс swagger-ui и я бы хотел, так сказать, вставить в него свои вещи.У меня сегодня есть файл с именем donkey.html , который обрабатывается при доступе к URL-адресу Swagger и выглядит следующим образом. 

...
<body>
  <div id="swagger-ui"></div>
  <div id="api_info"></div>
  <!-- ... -->
  <script src="./swagger-ui-bundle.js"></script>
  <script src="./swagger-ui-standalone-preset.js"></script>
  <script type="text/javascript">
    (function () { ... })();
  </script>
</body>
</html>

Я гуглил несколько часовсейчас и прочитайте много об OpenAPI и YAML среди прочего.Однако у меня сложилось впечатление, что он требует полной перестройки проекта Swagger, и мои амбиции на данный момент нацелены на гораздо более простую задачу.

Есть ли способ поднять DIV под названием api_info так он рендерит как часть swagger_ui без регенерации всего проекта Swagger?

Я попытался увеличить базовую схему, как показано здесь , но это плохо кончилось и оказалось немного сложнее, чем я нацеливаю.Возможно, это единственный возможный подход к созданию модуля, и в этом случае я рассмотрю его, но это последний ресурс в этом случае.

1 Ответ

0 голосов
/ 15 октября 2018

Swagger UI 3.x имеет систему плагинов, которая позволяет добавлять или изменять элементы пользовательского интерфейса.Некоторую документацию по плагинам можно найти по адресу:
Плагины
Каков предполагаемый способ настройки SwaggerUI 3.x?

Нет необходимостиперекомпилируйте Swagger UI для использования плагинов, вы можете определить плагины непосредственно на странице index.html.Чтобы добавить или изменить элементы пользовательского интерфейса, вам нужен плагин, который использует wrapComponents и React.createElement для построения желаемой структуры DOM.(См. Также Реагировать без JSX .)

Чтобы пользовательские плагины имели эффект, их необходимо добавить в список plugins в конструкторе SwaggerUIBundle.

Пример

Вот пример плагина, который добавляет пользовательские <h3> заголовки над и под заголовком API: 

// index.html

<script>
window.onload = function() {

  // Custom plugin that adds extra stuff
  const MyCustomPlugin = function() {
    return {
      wrapComponents: {
        // add text above InfoContainer - same effect as above title
        InfoContainer: (Original, { React }) => (props) => {
          return React.createElement("div", null,
            React.createElement("h3", null, "I'm above the InfoContainer"),
            React.createElement(Original, props)
          )
        },

        // and/or add text above API description
        InfoUrl: (Original, { React }) => (props) => {
          return React.createElement("div", null,
            React.createElement(Original, props),
            React.createElement("h3", null, "I'm above the API description")
          )
        }
      }
    }
  }


  const ui = SwaggerUIBundle({
    url: "http://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    ...
    plugins: [
      MyCustomPlugin,       // <------ add your custom plugin here
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    ...

Результат выглядит следующим образом:

Swagger UI with customized layour

...