智能文檔API文檔

1. 概述

完善的文檔對於無縫地與軟件交互至關重要，尤其是在為其他開發者使用 API 時。雖然我們有諸如 Swagger 之類的工具，但 Smart-Doc 引入了一種與現有開發實踐無縫集成的不同方法。

在本教程中，我們將學習 Smart-Doc 的基本知識，並演示如何在 Spring Boot 項目中進行設置。然後，我們將生成 HTML、 OpenAPI 規範格式和 Postman 集合格式的文檔。

2. 快速上手 Smart-Doc

Smart-Doc 是一個 Java 庫，可以自動生成多種格式的文檔，包括 HTML、AsciiDoc、Postman 和 OpenAPI。它不依賴於特殊註解，而是通過分析源代碼和現有的 Javadoc 註釋來生成準確、及時的文檔。

它支持多種類型的服務，包括 REST API、WebSockets 和 gRPC。此外，它與 Spring Boot、JMeter、JAX-RS 和 Quarkus 等框架和工具“開箱即用”。

要開始使用 Smart-Doc，我們需要在 resources 文件夾中定義一個配置文件。此文件通常包含服務器 URL 和輸出目錄等設置。

3. Maven 插件

要使用 Smart-Doc，我們需要將 <a href="https://mvnrepository.com/artifact/com.ly.smart-doc/smart-doc-maven-plugin">smart-doc-maven-plugin</a> 添加到我們的 <em>pom.xml</em> 中，並定義配置文件的路徑：

<plugin>
    <groupId>com.ly.smart-doc</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>3.1.1</version>
    <configuration>
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <projectName>Book API</projectName>
    </configuration>
</plugin>

此插件允許我們通過運行 Maven 命令生成 Smart-Doc 文檔。此外，我們還指定了用於生成文檔的配置文件的位置，並定義項目名稱。

接下來，我們定義一個名為 smart-doc.json 的配置文件，將其放置在 resources 文件夾中：

{
  "outPath": "./src/main/resources/doc",
  "serverUrl": "localhost:8080"
}

在此，我們定義 outPath，它指定生成的文檔保存的輸出目錄。 serverUrl 指定用於測試 API 請求的基礎服務器 URL。

4. Spring Boot 項目

為了理解 Smart-Doc 的工作原理，我們先創建一個 Spring Boot 項目，並將其包含 spring-boot-starter-web 到 pom.xml 中：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.5.4</version>
</dependency>

spring-boot-starter-web 依賴項允許我們使用嵌入式服務器構建 REST API。

4.1. 模型類

接下來，讓我們創建一個POJO類來表示一個實體：

public class Book {
    /**
     * Book ID
     */
    private Long id;

    /**
     * Author
     */
    private String author;

    /**
     * Book Title
     */
    private String title;

    /**
     * Book Price
     */
    private Double price;
}

在上面的代碼中，我們使用 Javadoc 註釋來記錄每個字段。

4.2. 倉庫類

接下來，我們創建一個倉庫類：

@Repository
public class BookRepository {
    private static final Map<Long, Book> books = new ConcurrentHashMap<>();

    static {
        Book book = new Book(1L, "George Martin", "A Song of Ice and Fire", 10000.00);
        books.put(1L, book);
    }

    public Optional<Book> findById(long id) {
        return Optional.ofNullable(books.get(id));
    }

    public void add(Book book) {
        books.put(book.getId(), book);
    }

    public List<Book> getBooks() {
        return new ArrayList<>(books.values());
    }

    public boolean delete(Book book) {
        return books.remove(book.getId(), book);
    }
}

在這裏，我們創建一個簡單的倉庫，並進行基本的創建、讀取、更新和刪除（CRUD）操作。

4.3. 控制器類

接下來，讓我們創建一個帶有詳細 Javadoc 的控制器類：

/**
 * The type Book controller.
 *
 * @author Baeldung.
 */
@RestController
@RequestMapping("/api/v1")
public class BookController {
    @Autowired
    private BookRepository bookRepository;

    /**
     * Create book.
     *
     * @param book the book
     * @return the book
     */
    @PostMapping("/books")
    public ResponseEntity<Book> createBook(@RequestBody Book book) {
        bookRepository.add(book);

        return ResponseEntity.ok(book);
    }

    /**
     * Get all books.
     *
     * @return the list
     */
    @GetMapping("/books")
    public ResponseEntity<List<Book>> getAllBooks() {
        return ResponseEntity.ok(bookRepository.getBooks());
    }

    /**
     * Gets book by id.
     *
     * @param bookId the book id|1
     * @return the book by id
     */
    @GetMapping("/book/{id}")
    public ResponseEntity<Book> getBookById(@PathVariable(value = "id") Long bookId) {
        Book book = bookRepository.findById(bookId)
          .orElseThrow(() -> new ResponseStatusException(HttpStatusCode.valueOf(404)));
        return ResponseEntity.ok(book);
    }

    /**
     * Update book response entity.
     *
     * @param bookId      the book id|1
     * @param bookDetails the book details
     * @return the response entity
     */
    @PutMapping("/books/{id}")
    public ResponseEntity<Book> updateBook(@PathVariable(value = "id") Long bookId, @Valid @RequestBody Book bookDetails) {
        Book book = bookRepository.findById(bookId)
          .orElseThrow(() -> new ResponseStatusException(HttpStatusCode.valueOf(404)));
        book.setAuthor(bookDetails.getAuthor());
        book.setPrice(bookDetails.getPrice());
        book.setTitle(bookDetails.getTitle());

        bookRepository.add(book);
        return ResponseEntity.ok(book);
    }

    /**
     * Delete book.
     *
     * @param bookId the book id|1
     * @return the true
     */
    @DeleteMapping("/book/{id}")
    public ResponseEntity<Boolean> deleteBook(@PathVariable(value = "id") Long bookId) {
        Book book = bookRepository.findById(bookId)
          .orElseThrow(() -> new ResponseStatusException(HttpStatusCode.valueOf(404)));
        return ResponseEntity.ok(bookRepository.delete(book));
    }
}

在上述代碼中，我們對所有控制器方法進行文檔記錄，並指定請求參數和返回值類型。

4.4. 生成文檔

最後，我們使用 Smart-Doc Maven 命令生成文檔：

$  mvn smart-doc:html

上述命令會生成 HTML 文檔，並將其保存在 resources/doc 目錄下：

api.html 文件包含文檔內容。

5. 審查 HTML 文檔

運行 Maven 命令後，讓我們打開 api.html文件以審查生成的文檔：

在左側，Smart-Doc 列出了所有控制器方法；單擊方法將導航到包含描述和參數詳細信息的詳細部分。

讓我們進一步向下滾動以查看有關“創建書”端點的更多詳細信息：

上面的表格顯示了預期的輸入類型、參數和返回值。參數描述直接來自實體類中的 Javadoc 註釋。

6. 生成 Postman 文檔

移動到下一步，我們來生成一份可以導入和在 Postman 中測試的文檔。為此，我們運行以下命令：

$ mvn smart-doc:postman

以上命令生成了一個 postman.json 文件在我們的輸出目錄中：

{
  "info": {
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "_postman_id": "91daa5c0-3bfe-4002-823b-875398e2bb2e",
    "name": "Book API"
  },
  "item": [
    {
      "name": "default",
      "item": [
        {
          "name": "The type Book controller.",
          "item": [
            {
              "name": "Create book.",
              "request": {
                "method": "POST",
                "body": {
                  "mode": "raw",
                  "raw": "{\n  \"id\": 0,\n  \"author\": \"\",\n  \"title\": \"\",\n  \"price\": 0.0\n}",
                  "options": {
                    "raw": {
                      "language": "json"
                    }
                  }
                },   
// ...
}

在這裏，我們看到了一些生成的 postman.json 文件的部分內容。它可以導入到 Postman 中，從而方便地直接測試 API 端點。

7. 生成 OpenAPI 規範

或者，我們可以生成 OpenAPI 規範，格式為 JSON 格式：

$ mvn smart-doc:openapi

此命令會在輸出目錄中生成一個 openapi.json 文件：

{
  "openapi": "3.1.0",
  "info": {
    "title": "Book API",
    "version": "v1.0.0"
  },
  "servers": [
    {
      "url": "localhost:8080"
    }
  ],
  "tags": [
    {
      "name": "BookController",
      "description": "The type Book controller."
    }
  ],
  "paths": {
    "/api/v1/books": {
      "post": {
        "summary": "Create book.",
        "deprecated": false,
        "tags": [
          "BookController"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/5d33d487e2ec7c29e2a7819f08a7c5f7"
              },
              "examples": {
                "json": {
                  "summary": "test data",
                  "value": "{\n  \"id\": 0,\n  \"author\": \"\",\n  \"title\": \"\",\n  \"price\": 0.0\n}"
                }
              }
            }
          }
        },
// ..
}

生成的JSON文件可以導入到Swagger編輯器中，從而渲染 Swagger UI 風格的文檔頁面。

8. 結論

在本文中，我們探討了如何使用 Smart-Doc 生成 API 文檔。我們演示了在一個簡單的 Spring Boot 項目中進行設置，使用 Javadoc 文檔類和控制器，並生成 HTML 和 OpenAPI、Postman 格式的輸出。

知識庫 / Spring / Spring Boot RSS 訂閱