JSON для API Reference

Структура верхнего уровня

Ключи корневого объекта — пространства имен. Значение каждого пространства имен — объект, ключами которого служат относительные имена типов. Для типов в глобальном пространстве имен используйте пустую строку. Вложенные типы записываются через точку, например Client.Options.

{
  "Acme.Sdk": {
    "Client": {
      "name": "Client",
      "summary": "Выполняет запросы к сервису Acme.",
      "declaration": "public sealed class Client",
      "type": 0,
      "access": "public",
      "isStatic": 0,
      "isAbstract": 0,
      "baseClass": "Object",
      "interfaces": ["IDisposable"],
      "members": []
    }
  }
}

Объекты пространства имен и типа обязательны. Некорректные значения пространств имен и типов пропускаются. У типа должен быть непустой ключ или поле name; поле declaration используется при создании стабильного маршрута viewer.

Поля типа

• name — имя типа относительно пространства имен. Если поле не задано, используется ключ объекта.
• summary — текст документации, обычно извлеченный из XML-тега summary.
• declaration — полная C#-декларация, которая отображается в справочнике.
• type — вид типа: 0 — class, 1 — interface, 2 — struct, 3 — enum, 4 — record. Также допустимы строки class, interface, struct, enum и record. По умолчанию используется class.
• access — модификатор доступа; значение по умолчанию — public.
• isStatic, isAbstract — логические флаги. Допустимы JSON boolean и значения 0/1.
• baseClass — имя базового класса.
• interfaces — массив имен реализованных интерфейсов.
• members — массив объектов членов типа.

Поля члена типа

Каждому члену нужны непустое поле name и числовое поле type больше нуля. Неподдерживаемые или неполные элементы пропускаются.

• type — 1 для поля или события, 2 для свойства, 3 для конструктора, метода или оператора, 4 для делегата, 5 для индексатора, 6 для значения enum. Элемент типа 1 со значением Action, Func или Predicate в valueType отображается как событие.
• name, declaration, summary и access описывают член и его отображаемую сигнатуру.
• valueType содержит тип поля, события, свойства, индексатора или возвращаемого значения.
• isStatic, isVirtual, isAbstract, isGeneric, hasGet и hasSet — логические флаги.
• parameters — массив объектов параметров.

При type: 3 имя .ctor создает конструктор. Статическое имя с префиксом op_ создает оператор, остальные значения — методы.

Пример члена

Следующий объект описывает публичный асинхронный метод. Поместите его в массив members нужного типа.

{
  "name": "GetAsync",
  "declaration": "public Task<Item> GetAsync(string id, CancellationToken cancellationToken = default)",
  "type": 3,
  "summary": "Возвращает объект по ID.",
  "access": "public",
  "isStatic": false,
  "isGeneric": false,
  "isVirtual": false,
  "isAbstract": false,
  "valueType": "Task<Item>",
  "parameters": [
    {
      "name": "id",
      "type": "string",
      "summary": "Идентификатор объекта."
    },
    {
      "name": "cancellationToken",
      "type": "CancellationToken",
      "summary": "Отменяет операцию.",
      "isOptional": true,
      "defaultValue": "default"
    }
  ]
}

Поля параметра

• name и type задают имя и тип параметра.
• summary содержит документацию параметра.
• refKind хранит модификатор ref, out или in.
• isOptional отмечает необязательный параметр, а defaultValue хранит отображаемое значение по умолчанию.

Полный пример

{
  "Acme.Sdk": {
    "Client": {
      "name": "Client",
      "summary": "Выполняет запросы к сервису Acme.",
      "declaration": "public sealed class Client : IDisposable",
      "type": 0,
      "baseClass": "Object",
      "interfaces": ["IDisposable"],
      "members": [
        {
          "name": ".ctor",
          "declaration": "public Client(string endpoint)",
          "type": 3,
          "summary": "Создает клиент.",
          "parameters": [
            {
              "name": "endpoint",
              "type": "string",
              "summary": "URL сервиса."
            }
          ]
        },
        {
          "name": "GetAsync",
          "declaration": "public Task<Item> GetAsync(string id, CancellationToken cancellationToken = default)",
          "type": 3,
          "summary": "Возвращает объект.",
          "valueType": "Task<Item>",
          "parameters": [
            { "name": "id", "type": "string", "summary": "Идентификатор объекта." },
            {
              "name": "cancellationToken",
              "type": "CancellationToken",
              "isOptional": 1,
              "defaultValue": "default"
            }
          ]
        }
      ]
    }
  }
}

Проверка и маршруты

Источник должен быть корректным JSON с объектом в корне. One File Docs нормализует и сортирует пространства имен, типы и группы членов. ID viewer формируются из деклараций, поэтому сохраняйте декларации стабильными и различайте сигнатуры перегруженных членов. После загрузки проверьте показанные редактором количества пространств имен, типов и членов перед сохранением или экспортом.