使用 Smart-Doc 的 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、WebSocket 和 gRPC 。此外，它還可以與 Spring Boot、JMeter、JAX-RS 和 Quarkus 等框架和工具開箱即用。
要開始使用 Smart-Doc，我們需要在resources資料夾中定義一個設定檔。該檔案通常包含伺服器 URL 和輸出目錄等設定。
3. Maven插件
要使用Smart-Doc，我們需要將[smart-doc-maven-plugin](https://mvnrepository.com/artifact/com.ly.smart-doc/smart-doc-maven-plugin)加入我們的pom.xml中並定義設定檔的路徑：
<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 文件。此外，我們指定了用於產生文件的設定檔的位置。最後，我們定義項目名稱。
接下來，讓我們在resources資料夾中定義一個名為smart-doc.json的設定檔：
{
"outPath": "./src/main/resources/doc",
"serverUrl": "localhost:8080"
}這裡，我們定義了outPath ，它指定了產生文件的保存輸出目錄。 serverUrl指定了用於測試 API 請求的基礎伺服器 URL。
4. Spring Boot 項目
為了了解 Smart-Doc 的工作原理，讓我們透過將spring-boot-starter-web新增至pom.xml來引導 Spring Boot 專案：
<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
上述指令在resources/doc目錄中產生 HTML 文件：
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規範
或者，我們可以產生 JSON 格式的 OpenAPI 規格：
$ 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 格式的輸出。
與往常一樣，範例的完整原始程式碼可在 GitHub 上找到。