XDoc: обсуждение в QQ группе: 820854691

XDoc — инструмент для создания документации по интерфейсам на основе Java-аннотаций

• Создание документации по интерфейсу на основе аннотаций Java без вмешательства в код, без необходимости использования дополнительных аннотаций, только с использованием комментариев к коду.
• Поддержка Spring Web, Spring Boot и JFinal.
• Поддерживает форматы вывода документации: Markdown и офлайн/онлайн HTML и другие.

Зачем использовать XDoc?

• Избежать написания дополнительной внешней документации по интерфейсам. Документация создаётся одновременно с кодом, что снижает необходимость в дополнительной поддержке.
• При изменении кода не нужно искать внешнюю документацию по интерфейсам, достаточно обратиться к комментариям в коде.
• Документация по интерфейсам управляется вместе с версиями, что упрощает откат и работу с несколькими средами и версиями.
• «Разве комментарии не должны быть частью корпоративного стандарта? Если в вашем стандарте нет раздела об интерфейсах, почему бы его не добавить? А если вы добавите раздел, то почему бы не использовать инструмент, который поможет вам создать документацию?»

Как использовать?

Рассмотрим пример использования со Spring Boot:

<!-- Добавляем зависимость Maven -->
<dependency>
    <groupId>com.github.treeleafj</groupId>
    <artifactId>spring-boot-starter-xDoc</artifactId>
    <version>1.1.0</version>
</dependency>

@EnableXDoc //<--- Добавляем эту аннотацию, чтобы включить XDOC для онлайн-документации HTML
@SpringBootApplication
public class TestApplication {

    public static void main(String[] args) {
        SpringApplication.run(TestApplication.class, args);
    }
}

# В application.properties настраиваем расположение проекта исходного кода.
# При использовании одномодульного Maven-проекта можно не настраивать.
xdoc.enable=true # Включаем XDoc, по умолчанию true. Рекомендуется изменить на false в рабочей среде.
xdoc.sourcePath=F:/java/project/xDoc/samples/sample-springboot/src/main/java   # Путь к исходному коду. Можно разделить несколько путей запятыми при использовании.
xdoc.title=Пользовательский интерфейс документации # Используется для настройки заголовка страницы документации.
xdoc.version=1.0 # Идентификатор версии документации интерфейса.

После выполнения этой подготовки конфигурация завершена.

Далее нам нужно написать контроллер и добавить комментарии:

/**
 * Модуль пользователя
 *
 * @author treeleaf
 * @date 2017-03-03 10:11
 */
@Controller
@RequestMapping("api/user")
public class UserController {

    /**
     * Вход в систему
     *
     * @param username Имя пользователя | Обязательный
     * @param password Пароль
     * @return Основная информация текущего вошедшего в систему пользователя
     * @resp code (0000 означает успешный вход в систему, другие значения указывают на неудачу) | string | Обязательный
     * @resp msg Информация о входе | string
     * @resp username Имя пользователя после успешного входа | string
     */
    @ResponseBody
    @PostMapping("login")
    public Map<String, String> login(String username, String password) {
        Map<String, String> model = new HashMap<>();
        model.put("code", "0000");
        model.put("msg", "Вход выполнен успешно");
        model.put("username", username);
        return model;
    }


    /**
     * Регистрация пользователя
     *
     * @param user :username Имя пользователя | Обязательный
     * @param user :password Пароль
     * @return Зарегистрированная основная информация пользователя
     * @respbody {"id":"123","password":"123456","username":"admin"}
     * @see User
     */
    @ResponseBody
    @RequestMapping(value = "register", method = {RequestMethod.POST, RequestMethod.PUT})
    User register(User user) {
        user.setId(UUID.randomUUID().toString());
        return user;
    }
}

После завершения написания кода просто запустите проект и перейдите по адресу: http://localhost:8080/xdoc/index.html

Что делать, если нужна автономная документация?

Поддерживается HTML:

/**
 * Создание автономной документации HTML-формата по интерфейсам
 */
@Test
public void buildHtml() throws Exception {
    /** Обратите внимание!!! Путь должен быть доступен для сканирования исходного кода проекта. Если сгенерированный файл не содержит информации об интерфейсе, это означает, что сканирование не удалось. Пожалуйста, сначала убедитесь, что переданный путь верен!!! */
    FileOutputStream out = new FileOutputStream(new File(userDir, "api.html"));
    XDoc xDoc = new XDoc(new File("F:/java/project/xDoc/samples/sample-springboot/src/main/java"), new SpringWebHttpFramework());
    xDoc.build(out, new HtmlForamt());
}

Также поддерживается Markdown:

/**
 * Создание автономной документации Markdown-формата по интерфейсам
 */
@Test
public void buildMarkdown() {
    /** Обратите внимание!!! Путь должен быть доступен для сканирования исходного кода проекта. Если сгенерированная документация Markdown не содержит информации об интерфейсе, это означает, что сканирование не удалось. Пожалуйста, сначала убедитесь, что переданный путь верен!!! */

    ByteArrayOutputStream out = new ByteArrayOutputStream();
    XDoc xDoc = new XDoc(new File("F:/java/project/xDoc/samples/sample-springboot/src/main/java"), new SpringWebHttpFramework());

    xDoc.build(out, new MarkdownFormat());

    System.out.println(out.toString());
}

Если используется не Spring Boot, а просто Spring Web или JFinal, как использовать, см. примеры в каталоге samples.

Использование существующих тегов комментариев:

• @title Заголовок интерфейса. Если этот тег не используется, по умолчанию используется описание из первой строки комментария интерфейса.

• @param Входящий параметр интерфейса. Формат: «Имя параметра Описание параметра | (Тип параметра) | (Обязателен ли параметр)». «Тип параметра» можно не указывать, по умолчанию это String. «Обязателен ли параметр» можно не указывать, по умолчанию параметр не обязателен. «Обязателен ли параметр» может принимать значения обязателен (Y) или необязателен (N). Примеры часто используемых форматов: имя пользователя Имя пользователя имя пользователя Имя пользователя|обязателен или имя пользователя Имя пользователя|Y имя пользователя Имя пользователя|необязателен или имя пользователя Имя пользователя|N имя пользователя Имя пользователя|String имя пользователя Имя пользователя|String|обязателен

  Для IDEA при использовании собственных комментариев Java @param, если имя параметра не совпадает с именем входящего параметра метода, IDEA выдаст ошибку. Чтобы избежать этого, перед именем параметра в комментариях можно добавить двоеточие (:), например: :имя пользователя Имя пользователя или пользователь :имя пользователя Имя пользователя.

• @paramObj Если входящие параметры находятся в объекте DTO, но неудобно добавлять комментарии @param для каждого параметра, можно использовать @paramObj для указания объекта DTO. Используется аналогично тегу @see, но @paramObj поддерживает наличие нескольких методов интерфейса. Одновременно можно использовать теги @param и @paramObj, при этом приоритет будет отдаваться тегам @param. Для примера обратитесь к файлу AccountController.java в каталоге samples. - @resp: указывает на возвращаемые параметры, формат аналогичен @param.

• @respbody: указывает демонстрационные данные возврата, в настоящее время поддерживает только форматирование данных JSON и используется только для демонстрации. Можно обратиться к UserController.java в разделе samples.

• @see: указывает объект возвращаемого параметра, аналогично @paramObj, но один — входной параметр, а другой — выходной. В одном методе может быть только одна аннотация @see. Если используются вместе с @resp, то приоритет у @resp. Можно обратиться к AccountController.java в разделе samples.

• @return: описание возвращаемой информации, содержимое представляет собой чистый текст, используется только для отображения.

• @IgnoreApi: это аннотация, которая не размещается над комментариями. Используется для обозначения того, какие интерфейсы не требуют создания документации по интерфейсу.