Тело запроса не отображается в примере curl с OpenApi3 + widdershins + shins

Question

Я создаю документацию по API для наших конечных точек Java. Я использую widdershins для преобразования нашего yaml-файла openAPI3.0 в уценку. Затем я использую shins для преобразования файла уценки в HTML. Тело запроса для всех наших конечных точек не отображается в сгенерированных примерах cURL. Почему это? Это противоречит цели наличия примеров cURL, потому что копирование и вставка примера cURL без требуемого тела не будет работать. Может ли кто-нибудь порекомендовать обходной путь или альтернативный инструмент, который генерирует хорошую документацию с полными примерами cURL?

Пример конечной точки из нашего файла openAPI.yaml...

post:
  tags:
  - Tools
  description: Installs a tool on a user's account
  operationId: Install Tool
  requestBody:
    description: UserTool object that needs to be installed on the user's account
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/UserTool'
    required: true
  parameters:
  responses:
    default:
      description: default response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Message'

Это документация, которую наша инструментальная цепочка генерирует из этого файла yaml... Мы хотели бы добавить строку, подобную приведенной ниже (выделено серым цветом), в наши примеры cURL. Это фрагмент файла уценки, который Виддершинс создает из нашего yaml-файла openAPI. Я вручную добавил - “d

Этот вопрос / ответ о переполнении стека подсказывает ответ: невозможно включить параметр body в пример кода с помощью swagger или openAPI. Это правильно? Если да, то почему? Что за рассуждение?

Ура, Гидеон

Answer 1

У меня тоже была такая же проблема. В результате проб и ошибок было обнаружено, что поведение, отображаемое на curl, зависит от значения in.

Пожалуйста, посмотрите на перечисление ParameterIn.

      public enum ParameterIn {
    DEFAULT(""),
    HEADER("header"),
    QUERY("query"),
    PATH("path"),
    COOKIE("cookie");

В первый раз я попробовал, как показано ниже:

      new Parameter().name("foo").in(ParameterIn.HEADER.name())

Но имя возвращается как «ЗАГОЛОВОК», поэтому чванство (или OpenAPI) распознается в заголовке. После перечисления ParameterIn должен быть нижний символ, например «заголовок».

Итак, вы можете исправить это так

      new Parameter().name("foo").in(ParameterIn.HEADER.toString())

или

      new Parameter().name("foo").in("header")

Answer 2

Я также столкнулся с той же проблемой, и я немного покопался. Оказывается, мне пришлось установить для опции options.httpSnippet в widdershins значение true, чтобы отображались параметры requestBody. Однако установка значения true показывает параметры только в том случае, если тип содержимого имеет значение application/json. Для multipart-form-data вам также необходимо установить для options.experimental значение true.

К сожалению, в widdershins есть ошибка для обработки application/x-www-form-urlencoded content-type. Я создал для него PR, который вы, вероятно, можете вручную исправить в пакете widdershins. PR-ссылка: https://github.com/Mermade/widdershins/pull/492/files