Минималистичный инструмент документирования Java RESTful API smalldoc

проект

GitHub.com/Лю Хуагуй/Да…Инструмент документации RESTful API, основанный на стандартных аннотациях Java.
smalldoc-antd-react-ui(GitHub.com/Лю Хуагуй/Да…

Зачем строить колеса?

Обсессивно-компульсивные пациенты, неприемлемыеSwaggerВнедрение различных аннотаций в код усложняется, и он больше стремится очистить код;
Использование аннотаций требует определенных затрат на обучение;
Затем попробуйте использоватьApidoc, хотя Apidoc формирует документы на основе аннотаций, стоимость обучения не снижается, нужно учить дополнительные аннотацииTag, и вы должны использовать эти специальныеTagВручную выпишите соответствующую информацию о нужном вам интерфейсе, и я чувствую, что рабочая нагрузка по написанию документов не сильно уменьшилась;
Есть также некоторые проекты, которые генерируют документы на основе стандартных аннотаций Java, но некоторые не могут поддерживать параметры сущности, общие переменные и многомодульные зависимости.У некоторых слишком много ошибок, интерфейс пользовательского интерфейса недостаточно удобен, использование слишком сложно, и есть даже проблемы с логической обработкой.

характеристика

Создавайте документы на основе исходного кода Java, стандартных аннотаций и тегов, без вмешательства в код, гарантируйте чистоту кода и соблюдение привычек разработчиков в отношении аннотаций и спецификаций аннотаций.
Предоставляет дружественный пользовательский интерфейс по умолчанию
Предоставляется документированный RESTEful API для поддержки реализации пользовательского пользовательского интерфейса.
Обеспечьте стандартизированный метод конфигурации, который более удобен в использовании
Обеспечить соответствующий пружинный загрузочный стартер, поддерживая при этом традиционные пружинные и пружинные загрузочные
Поддержка связанных параметров сущности
Поддерживаются дженерики
Поддержка игнорирования параметра
Поддерживает структуры данных, которые игнорируют синтаксический анализ указанного пакета или параметров указанного типа.
Поддержка многомодульного проекта (разбор исходного кода или структуры данных из указанного пакета Jar)

Метод реализации

Проанализируйте файл исходного кода и сгенерируйте информацию о документе с помощью исходного кода и комментариев к нему. Теги, используемые в аннотациях до сих пор, являются стандартными тегами аннотаций Java, и в будущем могут быть добавлены некоторые необходимые пользовательские теги, и даже возможно предоставить механизм расширения тегов - пользовательские теги пользователей и методы обработки пользовательских тегов. .
Думая о создании документов Java RESTful API, первое, о чем следует подумать, это то, как создаются документы Java API, поэтому способ анализа исходного кода не выбран.com.github.javaparser » javaparser-coreилиcom.thoughtworks.qdox » qdox, вместо этого выберите собственный JDKJavadoc Tool(docs.Oracle.com/en/java/ только что…API, соответствующий инструменту,Javadoc API(docs.Oracle.com/en/java/ только что…
Поскольку автор все еще используетJava8, поэтому реализация проекта полностью основана наУстаревший API Javadoc
- Package com.sun.tools.javadoc (docs.Oracle.com/en/java/ только что…)
- Package com.sun.javadoc (docs.Oracle.com/en/java/ только что…)
в:

Module jdk.javadoc Package com.sun.tools.javadoc This package and its contents are deprecated and may be removed in a future release. See javax.tools.ToolProvider.getSystemDocumentationTool and javax.tools.DocumentationTool for replacement functionality.

Module jdk.javadoc Package com.sun.javadoc Note: The declarations in this package have been superseded by those in the package jdk.javadoc.doclet. For more information, see the Migration Guide in the documentation for that package.
```
@Deprecated(since="9",forRemoval=true)
public class Main extends Object
```
Как видно, устаревший API JavadocJava9был помечен как заброшенный и будет удален в ближайшем будущем, но, к счастью, до последнего крупного релиза.Java12API не был удален, поэтому используйтеJava12Пользователи предыдущих версий и предыдущих версий могут использовать его с уверенностью, а последующие авторы предоставят поддержку API новой версии.
Пользовательский интерфейс основан наcreate-react-appиantdРазработано одностраничное приложение ——smalldoc-antd-react-ui(GitHub.com/Лю Хуагуй/Да…

использовать

Пример представляет собой проект с весенней загрузкой, использующийapplication.ymlкак файл конфигурации

импортировать зависимости

<dependency>
    <groupId>com.github.liuhuagui</groupId>
    <artifactId>smalldoc-spring-boot-starter</artifactId>
    <version>2.3</version>
</dependency>

настроить

Документ интерфейса обычно используется во время разработки, и необходимо только убедиться, что конфигурация документа действует в среде разработки ——spring.profiles.active=dev

server: 
  port: 8080
  servlet:
    context-path: /my-project
spring: 
  profiles:
    active: dev
---
spring:
  profiles: dev
smalldoc:
  source-paths: #额外的源码路径（项目的源码路径默认已经包含在内，不需要再添加）
    - 'D:\Workspaces\myBeanProject\my-bean\src\main\java'
    - 'D:\Maven\Repositories\repository\com\aliyun\aliyun-java-sdk-core\3.5.0'
  packages:
    - quantity.knowledgebase
    - my.bean
    - com.aliyuncs.auth.sts
  project-name: 我的文档
  enabled: true #默认为true
  url-pattern: /smalldoc/* #默认为/smalldoc/*

адрес

URL: http://192.168.1.76:8080/my-project/smalldoc/
METHOD: GET

Исходный код интерфейса

/**
 * 文章的创建，编辑，发布，自定义
 * @author KaiKang 799600902@qq.com
 */
@RestController
@RequestMapping("w")
public class WriteArticleController {
    /**
     * 原创文章在编辑中保存
     * @param content 内容
     * @param oaCopy  原创文章副本
     * @return data-草稿ID
     * @author KaiKang 799600902@qq.com
     */
    @PostMapping(path = "o/save_draft",produces = {"text/plain", "application/json;charset=UTF-8"},consumes = "application/x-www-form-urlencoded")
    public Result<Long> saveOriginalDraft(String content, OriginalArticleCopy oaCopy, HttpServletRequest request) {
        return writeArticleService.saveOriginalDraft(content, oaCopy);
    }

    /**
     * 这只是一个测试接口
     * @param content 内容
     * @return 返回数据
     * @author KaiKang 799600902@qq.com
     */
    @GetMapping(path = "o/save",produces = {"text/plain", "application/json;charset=UTF-8"})
    public Result<OriginalArticle> save(String content, HttpServletRequest request) {
        return null;
    }
}

документация по интерфейсу

API документации (используется для реализации пользовательского интерфейса)

URL: http://192.168.1.76:8080/my-project/smalldoc/
METHOD: POST

Уведомление

source-pathsЭлемент конфигурации представляет собой дополнительный путь к исходному коду. Путь к исходному коду проекта уже включен по умолчанию, и никаких дополнительных дополнений не требуется. Вам нужно только указать отсканированный пакет, например:my.project.controller
Программа будет разрешать только имя класса*ControllerИнформация об интерфейсе (спецификация) в исходном коде
Программа еще не поддерживает среду Linux. Прежде чем проект будет упакован и развернут, не забудьте закрыть функцию документа. Существуют различные способы ее закрытия, такие как:
1. spring.profiles.active=*(*Пока это не dev), больше не активировать конфигурацию среды разработки
2. smalldoc.enabled=false, отключить включить
3. Измените область зависимости наtestЗатем упакуйте его, чтобыsmalldocПакет jar не будет упакован (рекомендуется)
```
 <dependency>
   	<groupId>com.github.liuhuagui</groupId>
   	<artifactId>smalldoc-spring-boot-starter</artifactId>
   	<version>2.3</version>
   	<scope>test</scope>
 </dependency>
```

Сообщество

Если вам нужна помощь во время использования или вы хотите добавить некоторые функции в проект, пожалуйста, отправьте ——GitHub.com/Лю Хуагуй/Да…