Просмотр исходного кода

✨ (markup): 新增 POST /v3/markup-previews,把未保存的源码渲染成节点树

模板生成器、编辑器的预览用:不写库(200),要登录,口径同阅读页读模式;
给了 channels 的逐个判读权限(403 / 404)。源码里模板自带的 channel
在渲染器内部取数、不判可见性,留 FIXME 在 MarkupPreviewService。
新能力,没有一一对应的 v2 端点(v2 article-preview 绑定文章、走旧渲染器,原样保留)。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
visuddhinanda 2 дней назад
Родитель
Сommit
262dab4fb7

+ 29 - 0
api-test/cases/25_markup_previews.php

@@ -0,0 +1,29 @@
+<?php
+
+use \WikipaliApi\Api\MarkupPreviewsApi;
+use \WikipaliApi\Model\PostApiV3MarkupPreviewsRequest;
+
+/*
+ * 源码预览:POST /v3/markup-previews(模板生成器的预览)。要登录,不写库。
+ * 各服务器数据不同,只核对形状;按 channel 查术语、私有 channel 403 由 api-v13 的 MarkupPreviewV3Test 覆盖。
+ */
+
+test('POST /v3/markup-previews → 200,body 是节点树', function () {
+    $token = required_token();
+    $body = new PostApiV3MarkupPreviewsRequest();
+    $body->setContent("**粗体** {{quality|featured}}\n\n{{v|url=https://example.com/a.mp4|title=x}}");
+    $res = request(fn () => api(MarkupPreviewsApi::class, $token)->postApiV3MarkupPreviewsWithHttpInfo($body));
+    assert_status(200, $res, 'markup preview');
+    $nodes = $res['body']['data']['body'] ?? null;
+    assert_eq(true, is_array($nodes) && count($nodes) > 0, 'body 不为空');
+    $json = json_encode($nodes);
+    assert_eq([true, true], [str_contains($json, '"name":"quality"'), str_contains($json, '"name":"video"')], '模板节点');
+});
+
+test('POST /v3/markup-previews:无 token → 401,缺 content → 422', function () {
+    $anon = raw('POST', '/v3/markup-previews', null, ['content' => 'x']);
+    assert_status(401, $anon, '无 token');
+    $bad = raw('POST', '/v3/markup-previews', null, ['content_type' => 'html'], required_token());
+    assert_status(422, $bad, '缺 content');
+    assert_field_error('content', $bad, '缺 content');
+});

+ 12 - 0
api-test/client/.openapi-generator/FILES

@@ -20,6 +20,7 @@ docs/Api/GlossariesApi.md
 docs/Api/GroupsApi.md
 docs/Api/GroupsApi.md
 docs/Api/HeartbeatApi.md
 docs/Api/HeartbeatApi.md
 docs/Api/InvitesApi.md
 docs/Api/InvitesApi.md
+docs/Api/MarkupPreviewsApi.md
 docs/Api/MeApi.md
 docs/Api/MeApi.md
 docs/Api/NissayaCardsApi.md
 docs/Api/NissayaCardsApi.md
 docs/Api/PaliWordFormsApi.md
 docs/Api/PaliWordFormsApi.md
@@ -246,6 +247,9 @@ docs/Model/PostApiV3GroupsRequest.md
 docs/Model/PostApiV3Invites200Response.md
 docs/Model/PostApiV3Invites200Response.md
 docs/Model/PostApiV3Invites200ResponseData.md
 docs/Model/PostApiV3Invites200ResponseData.md
 docs/Model/PostApiV3InvitesRequest.md
 docs/Model/PostApiV3InvitesRequest.md
+docs/Model/PostApiV3MarkupPreviews200Response.md
+docs/Model/PostApiV3MarkupPreviews200ResponseData.md
+docs/Model/PostApiV3MarkupPreviewsRequest.md
 docs/Model/PostApiV3MeReactions200Response.md
 docs/Model/PostApiV3MeReactions200Response.md
 docs/Model/PostApiV3MeReactionsRequest.md
 docs/Model/PostApiV3MeReactionsRequest.md
 docs/Model/PostApiV3MeReadingTime200Response.md
 docs/Model/PostApiV3MeReadingTime200Response.md
@@ -281,6 +285,7 @@ lib/Api/GlossariesApi.php
 lib/Api/GroupsApi.php
 lib/Api/GroupsApi.php
 lib/Api/HeartbeatApi.php
 lib/Api/HeartbeatApi.php
 lib/Api/InvitesApi.php
 lib/Api/InvitesApi.php
+lib/Api/MarkupPreviewsApi.php
 lib/Api/MeApi.php
 lib/Api/MeApi.php
 lib/Api/NissayaCardsApi.php
 lib/Api/NissayaCardsApi.php
 lib/Api/PaliWordFormsApi.php
 lib/Api/PaliWordFormsApi.php
@@ -512,6 +517,9 @@ lib/Model/PostApiV3GroupsRequest.php
 lib/Model/PostApiV3Invites200Response.php
 lib/Model/PostApiV3Invites200Response.php
 lib/Model/PostApiV3Invites200ResponseData.php
 lib/Model/PostApiV3Invites200ResponseData.php
 lib/Model/PostApiV3InvitesRequest.php
 lib/Model/PostApiV3InvitesRequest.php
+lib/Model/PostApiV3MarkupPreviews200Response.php
+lib/Model/PostApiV3MarkupPreviews200ResponseData.php
+lib/Model/PostApiV3MarkupPreviewsRequest.php
 lib/Model/PostApiV3MeReactions200Response.php
 lib/Model/PostApiV3MeReactions200Response.php
 lib/Model/PostApiV3MeReactionsRequest.php
 lib/Model/PostApiV3MeReactionsRequest.php
 lib/Model/PostApiV3MeReadingTime200Response.php
 lib/Model/PostApiV3MeReadingTime200Response.php
@@ -548,6 +556,7 @@ test/Api/GlossariesApiTest.php
 test/Api/GroupsApiTest.php
 test/Api/GroupsApiTest.php
 test/Api/HeartbeatApiTest.php
 test/Api/HeartbeatApiTest.php
 test/Api/InvitesApiTest.php
 test/Api/InvitesApiTest.php
+test/Api/MarkupPreviewsApiTest.php
 test/Api/MeApiTest.php
 test/Api/MeApiTest.php
 test/Api/NissayaCardsApiTest.php
 test/Api/NissayaCardsApiTest.php
 test/Api/PaliWordFormsApiTest.php
 test/Api/PaliWordFormsApiTest.php
@@ -774,6 +783,9 @@ test/Model/PostApiV3GroupsRequestTest.php
 test/Model/PostApiV3Invites200ResponseDataTest.php
 test/Model/PostApiV3Invites200ResponseDataTest.php
 test/Model/PostApiV3Invites200ResponseTest.php
 test/Model/PostApiV3Invites200ResponseTest.php
 test/Model/PostApiV3InvitesRequestTest.php
 test/Model/PostApiV3InvitesRequestTest.php
+test/Model/PostApiV3MarkupPreviews200ResponseDataTest.php
+test/Model/PostApiV3MarkupPreviews200ResponseTest.php
+test/Model/PostApiV3MarkupPreviewsRequestTest.php
 test/Model/PostApiV3MeReactions200ResponseTest.php
 test/Model/PostApiV3MeReactions200ResponseTest.php
 test/Model/PostApiV3MeReactionsRequestTest.php
 test/Model/PostApiV3MeReactionsRequestTest.php
 test/Model/PostApiV3MeReadingTime200ResponseDataTest.php
 test/Model/PostApiV3MeReadingTime200ResponseDataTest.php

+ 532 - 0
api-test/client/lib/Api/MarkupPreviewsApi.php

@@ -0,0 +1,532 @@
+<?php
+/**
+ * MarkupPreviewsApi
+ * PHP version 8.1
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ */
+
+/**
+ * MINT API
+ *
+ * International Academy Of Pali Tipitaka(国际巴利三藏学院)  由 `php openapi/scripts/generate.php` 依据 api-v13 的路由与控制器源码生成。 响应统一封装为 `{ok, message, data}`;`ok=false` 时 `message` 为错误信息。
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * Generated by: https://openapi-generator.tech
+ * Generator version: 7.25.0
+ */
+
+/**
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+namespace WikipaliApi\Api;
+
+use GuzzleHttp\Client;
+use GuzzleHttp\ClientInterface;
+use GuzzleHttp\Exception\ConnectException;
+use GuzzleHttp\Exception\RequestException;
+use GuzzleHttp\Psr7\MultipartStream;
+use GuzzleHttp\Psr7\Request;
+use GuzzleHttp\RequestOptions;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+use WikipaliApi\ApiException;
+use WikipaliApi\Configuration;
+use WikipaliApi\FormDataProcessor;
+use WikipaliApi\HeaderSelector;
+use WikipaliApi\ObjectSerializer;
+
+/**
+ * MarkupPreviewsApi Class Doc Comment
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ */
+class MarkupPreviewsApi
+{
+    /**
+     * @var ClientInterface
+     */
+    protected $client;
+
+    /**
+     * @var Configuration
+     */
+    protected $config;
+
+    /**
+     * @var HeaderSelector
+     */
+    protected $headerSelector;
+
+    /**
+     * @var int Host index
+     */
+    protected $hostIndex;
+
+    /** @var string[] $contentTypes **/
+    public const contentTypes = [
+        'postApiV3MarkupPreviews' => [
+            'application/json',
+        ],
+    ];
+
+    /**
+     * @param ClientInterface $client
+     * @param Configuration   $config
+     * @param HeaderSelector  $selector
+     * @param int             $hostIndex (Optional) host index to select the list of hosts if defined in the OpenAPI spec
+     */
+    public function __construct(
+        ?ClientInterface $client = null,
+        ?Configuration $config = null,
+        ?HeaderSelector $selector = null,
+        int $hostIndex = 0
+    ) {
+        $this->client = $client ?: new Client();
+        $this->config = $config ?: Configuration::getDefaultConfiguration();
+        $this->headerSelector = $selector ?: new HeaderSelector();
+        $this->hostIndex = $hostIndex;
+    }
+
+    /**
+     * Set the host index
+     *
+     * @param int $hostIndex Host index (required)
+     */
+    public function setHostIndex($hostIndex): void
+    {
+        $this->hostIndex = $hostIndex;
+    }
+
+    /**
+     * Get the host index
+     *
+     * @return int Host index
+     */
+    public function getHostIndex()
+    {
+        return $this->hostIndex;
+    }
+
+    /**
+     * @return Configuration
+     */
+    public function getConfig()
+    {
+        return $this->config;
+    }
+
+    /**
+     * Operation postApiV3MarkupPreviews
+     *
+     * 预览一段源码
+     *
+     * @param  \WikipaliApi\Model\PostApiV3MarkupPreviewsRequest $post_api_v3_markup_previews_request post_api_v3_markup_previews_request (required)
+     * @param  string $contentType The value for the Content-Type header. Check self::contentTypes['postApiV3MarkupPreviews'] to see the possible values for this operation
+     *
+     * @throws \WikipaliApi\ApiException on non-2xx response or if the response body is not in the expected format
+     * @throws \InvalidArgumentException
+     * @return \WikipaliApi\Model\PostApiV3MarkupPreviews200Response|\WikipaliApi\Model\ProblemDetails|\WikipaliApi\Model\ProblemDetails|\WikipaliApi\Model\ProblemDetails|\WikipaliApi\Model\ProblemDetails
+     */
+    public function postApiV3MarkupPreviews($post_api_v3_markup_previews_request, string $contentType = self::contentTypes['postApiV3MarkupPreviews'][0])
+    {
+        list($response) = $this->postApiV3MarkupPreviewsWithHttpInfo($post_api_v3_markup_previews_request, $contentType);
+        return $response;
+    }
+
+    /**
+     * Operation postApiV3MarkupPreviewsWithHttpInfo
+     *
+     * 预览一段源码
+     *
+     * @param  \WikipaliApi\Model\PostApiV3MarkupPreviewsRequest $post_api_v3_markup_previews_request (required)
+     * @param  string $contentType The value for the Content-Type header. Check self::contentTypes['postApiV3MarkupPreviews'] to see the possible values for this operation
+     *
+     * @throws \WikipaliApi\ApiException on non-2xx response or if the response body is not in the expected format
+     * @throws \InvalidArgumentException
+     * @return array of \WikipaliApi\Model\PostApiV3MarkupPreviews200Response|\WikipaliApi\Model\ProblemDetails|\WikipaliApi\Model\ProblemDetails|\WikipaliApi\Model\ProblemDetails|\WikipaliApi\Model\ProblemDetails, HTTP status code, HTTP response headers (array of strings)
+     */
+    public function postApiV3MarkupPreviewsWithHttpInfo($post_api_v3_markup_previews_request, string $contentType = self::contentTypes['postApiV3MarkupPreviews'][0])
+    {
+        $request = $this->postApiV3MarkupPreviewsRequest($post_api_v3_markup_previews_request, $contentType);
+
+        try {
+            $options = $this->createHttpClientOption();
+            try {
+                $response = $this->client->send($request, $options);
+            } catch (RequestException $e) {
+                throw new ApiException(
+                    "[{$e->getCode()}] {$e->getMessage()}",
+                    (int) $e->getCode(),
+                    $e->getResponse() ? $e->getResponse()->getHeaders() : null,
+                    $e->getResponse() ? (string) $e->getResponse()->getBody() : null
+                );
+            } catch (ConnectException $e) {
+                throw new ApiException(
+                    "[{$e->getCode()}] {$e->getMessage()}",
+                    (int) $e->getCode(),
+                    null,
+                    null
+                );
+            }
+
+            $statusCode = $response->getStatusCode();
+
+
+            switch($statusCode) {
+                case 200:
+                    return $this->handleResponseWithDataType(
+                        '\WikipaliApi\Model\PostApiV3MarkupPreviews200Response',
+                        $request,
+                        $response,
+                    );
+                case 401:
+                    return $this->handleResponseWithDataType(
+                        '\WikipaliApi\Model\ProblemDetails',
+                        $request,
+                        $response,
+                    );
+                case 403:
+                    return $this->handleResponseWithDataType(
+                        '\WikipaliApi\Model\ProblemDetails',
+                        $request,
+                        $response,
+                    );
+                case 404:
+                    return $this->handleResponseWithDataType(
+                        '\WikipaliApi\Model\ProblemDetails',
+                        $request,
+                        $response,
+                    );
+                case 422:
+                    return $this->handleResponseWithDataType(
+                        '\WikipaliApi\Model\ProblemDetails',
+                        $request,
+                        $response,
+                    );
+            }
+
+            
+
+            if ($statusCode < 200 || $statusCode > 299) {
+                throw new ApiException(
+                    sprintf(
+                        '[%d] Error connecting to the API (%s)',
+                        $statusCode,
+                        (string) $request->getUri()
+                    ),
+                    $statusCode,
+                    $response->getHeaders(),
+                    (string) $response->getBody()
+                );
+            }
+
+            return $this->handleResponseWithDataType(
+                '\WikipaliApi\Model\PostApiV3MarkupPreviews200Response',
+                $request,
+                $response,
+            );
+        } catch (ApiException $e) {
+            switch ($e->getCode()) {
+                case 200:
+                    $data = ObjectSerializer::deserialize(
+                        $e->getResponseBody(),
+                        '\WikipaliApi\Model\PostApiV3MarkupPreviews200Response',
+                        $e->getResponseHeaders()
+                    );
+                    $e->setResponseObject($data);
+                    throw $e;
+                case 401:
+                    $data = ObjectSerializer::deserialize(
+                        $e->getResponseBody(),
+                        '\WikipaliApi\Model\ProblemDetails',
+                        $e->getResponseHeaders()
+                    );
+                    $e->setResponseObject($data);
+                    throw $e;
+                case 403:
+                    $data = ObjectSerializer::deserialize(
+                        $e->getResponseBody(),
+                        '\WikipaliApi\Model\ProblemDetails',
+                        $e->getResponseHeaders()
+                    );
+                    $e->setResponseObject($data);
+                    throw $e;
+                case 404:
+                    $data = ObjectSerializer::deserialize(
+                        $e->getResponseBody(),
+                        '\WikipaliApi\Model\ProblemDetails',
+                        $e->getResponseHeaders()
+                    );
+                    $e->setResponseObject($data);
+                    throw $e;
+                case 422:
+                    $data = ObjectSerializer::deserialize(
+                        $e->getResponseBody(),
+                        '\WikipaliApi\Model\ProblemDetails',
+                        $e->getResponseHeaders()
+                    );
+                    $e->setResponseObject($data);
+                    throw $e;
+            }
+        
+
+            throw $e;
+        }
+    }
+
+    /**
+     * Operation postApiV3MarkupPreviewsAsync
+     *
+     * 预览一段源码
+     *
+     * @param  \WikipaliApi\Model\PostApiV3MarkupPreviewsRequest $post_api_v3_markup_previews_request (required)
+     * @param  string $contentType The value for the Content-Type header. Check self::contentTypes['postApiV3MarkupPreviews'] to see the possible values for this operation
+     *
+     * @throws \InvalidArgumentException
+     * @return \GuzzleHttp\Promise\PromiseInterface
+     */
+    public function postApiV3MarkupPreviewsAsync($post_api_v3_markup_previews_request, string $contentType = self::contentTypes['postApiV3MarkupPreviews'][0])
+    {
+        return $this->postApiV3MarkupPreviewsAsyncWithHttpInfo($post_api_v3_markup_previews_request, $contentType)
+            ->then(
+                function ($response) {
+                    return $response[0];
+                }
+            );
+    }
+
+    /**
+     * Operation postApiV3MarkupPreviewsAsyncWithHttpInfo
+     *
+     * 预览一段源码
+     *
+     * @param  \WikipaliApi\Model\PostApiV3MarkupPreviewsRequest $post_api_v3_markup_previews_request (required)
+     * @param  string $contentType The value for the Content-Type header. Check self::contentTypes['postApiV3MarkupPreviews'] to see the possible values for this operation
+     *
+     * @throws \InvalidArgumentException
+     * @return \GuzzleHttp\Promise\PromiseInterface
+     */
+    public function postApiV3MarkupPreviewsAsyncWithHttpInfo($post_api_v3_markup_previews_request, string $contentType = self::contentTypes['postApiV3MarkupPreviews'][0])
+    {
+        $returnType = '\WikipaliApi\Model\PostApiV3MarkupPreviews200Response';
+        $request = $this->postApiV3MarkupPreviewsRequest($post_api_v3_markup_previews_request, $contentType);
+
+        return $this->client
+            ->sendAsync($request, $this->createHttpClientOption())
+            ->then(
+                function ($response) use ($returnType) {
+                    if ($returnType === '\SplFileObject') {
+                        $content = $response->getBody(); //stream goes to serializer
+                    } else {
+                        $content = (string) $response->getBody();
+                        if ($returnType !== 'string') {
+                            $content = json_decode($content);
+                        }
+                    }
+
+                    return [
+                        ObjectSerializer::deserialize($content, $returnType, []),
+                        $response->getStatusCode(),
+                        $response->getHeaders()
+                    ];
+                },
+                function ($exception) {
+                    $response = $exception->getResponse();
+                    $statusCode = $response->getStatusCode();
+                    throw new ApiException(
+                        sprintf(
+                            '[%d] Error connecting to the API (%s)',
+                            $statusCode,
+                            $exception->getRequest()->getUri()
+                        ),
+                        $statusCode,
+                        $response->getHeaders(),
+                        (string) $response->getBody()
+                    );
+                }
+            );
+    }
+
+    /**
+     * Create request for operation 'postApiV3MarkupPreviews'
+     *
+     * @param  \WikipaliApi\Model\PostApiV3MarkupPreviewsRequest $post_api_v3_markup_previews_request (required)
+     * @param  string $contentType The value for the Content-Type header. Check self::contentTypes['postApiV3MarkupPreviews'] to see the possible values for this operation
+     *
+     * @throws \InvalidArgumentException
+     * @return \GuzzleHttp\Psr7\Request
+     */
+    public function postApiV3MarkupPreviewsRequest($post_api_v3_markup_previews_request, string $contentType = self::contentTypes['postApiV3MarkupPreviews'][0])
+    {
+
+        // verify the required parameter 'post_api_v3_markup_previews_request' is set
+        if ($post_api_v3_markup_previews_request === null || (is_array($post_api_v3_markup_previews_request) && count($post_api_v3_markup_previews_request) === 0)) {
+            throw new \InvalidArgumentException(
+                'Missing the required parameter $post_api_v3_markup_previews_request when calling postApiV3MarkupPreviews'
+            );
+        }
+
+
+        $resourcePath = '/v3/markup-previews';
+        $formParams = [];
+        $queryParams = [];
+        $headerParams = [];
+        $httpBody = '';
+        $multipart = false;
+
+
+
+
+
+        $headers = $this->headerSelector->selectHeaders(
+            ['application/json', 'application/problem+json', ],
+            $contentType,
+            $multipart
+        );
+
+        // for model (json/xml)
+        if (isset($post_api_v3_markup_previews_request)) {
+            if (stripos($headers['Content-Type'], 'application/json') !== false) {
+                # if Content-Type contains "application/json", json_encode the body
+                try {
+                    $httpBody = json_encode(ObjectSerializer::sanitizeForSerialization($post_api_v3_markup_previews_request), JSON_THROW_ON_ERROR);
+                } catch (\JsonException $e) {
+                    throw new \InvalidArgumentException('json_encode error: ' . $e->getMessage(), 0, $e);
+                }
+            } else {
+                $httpBody = $post_api_v3_markup_previews_request;
+            }
+        } elseif (count($formParams) > 0) {
+            if ($multipart) {
+                $multipartContents = [];
+                foreach ($formParams as $formParamName => $formParamValue) {
+                    $formParamValueItems = is_array($formParamValue) ? $formParamValue : [$formParamValue];
+                    foreach ($formParamValueItems as $formParamValueItem) {
+                        $multipartContents[] = [
+                            'name' => $formParamName,
+                            'contents' => $formParamValueItem
+                        ];
+                    }
+                }
+                // for HTTP post (form)
+                $httpBody = new MultipartStream($multipartContents);
+
+            } elseif (stripos($headers['Content-Type'], 'application/json') !== false) {
+                # if Content-Type contains "application/json", json_encode the form parameters
+                try {
+                    $httpBody = json_encode($formParams, JSON_THROW_ON_ERROR);
+                } catch (\JsonException $e) {
+                    throw new \InvalidArgumentException('json_encode error: ' . $e->getMessage(), 0, $e);
+                }
+            } else {
+                // for HTTP post (form)
+                $httpBody = ObjectSerializer::buildQuery($formParams);
+            }
+        }
+
+        // this endpoint requires Bearer authentication (access token)
+        if (!empty($this->config->getAccessToken())) {
+            $headers['Authorization'] = 'Bearer ' . $this->config->getAccessToken();
+        }
+
+        $defaultHeaders = [];
+        if ($this->config->getUserAgent()) {
+            $defaultHeaders['User-Agent'] = $this->config->getUserAgent();
+        }
+
+        $headers = array_merge(
+            $defaultHeaders,
+            $headerParams,
+            $headers
+        );
+
+        $operationHost = $this->config->getHost();
+        $query = ObjectSerializer::buildQuery($queryParams);
+        return new Request(
+            'POST',
+            $operationHost . $resourcePath . ($query ? "?{$query}" : ''),
+            $headers,
+            $httpBody
+        );
+    }
+
+    /**
+     * Create http client option
+     *
+     * @throws \RuntimeException on file opening failure
+     * @return array of http client options
+     */
+    protected function createHttpClientOption()
+    {
+        $options = [];
+        if ($this->config->getDebug()) {
+            $options[RequestOptions::DEBUG] = fopen($this->config->getDebugFile(), 'a');
+            if (!$options[RequestOptions::DEBUG]) {
+                throw new \RuntimeException('Failed to open the debug file: ' . $this->config->getDebugFile());
+            }
+        }
+
+        if ($this->config->getCertFile()) {
+            $options[RequestOptions::CERT] = $this->config->getCertFile();
+        }
+
+        if ($this->config->getKeyFile()) {
+            $options[RequestOptions::SSL_KEY] = $this->config->getKeyFile();
+        }
+
+        return $options;
+    }
+
+    private function handleResponseWithDataType(
+        string $dataType,
+        RequestInterface $request,
+        ResponseInterface $response
+    ): array {
+        if ($dataType === '\SplFileObject') {
+            $content = $response->getBody(); //stream goes to serializer
+        } else {
+            $content = (string) $response->getBody();
+            if ($dataType !== 'string') {
+                try {
+                    $content = json_decode($content, false, 512, JSON_THROW_ON_ERROR);
+                } catch (\JsonException $exception) {
+                    throw new ApiException(
+                        sprintf(
+                            'Error JSON decoding server response (%s)',
+                            $request->getUri()
+                        ),
+                        $response->getStatusCode(),
+                        $response->getHeaders(),
+                        $content
+                    );
+                }
+            }
+        }
+
+        return [
+            ObjectSerializer::deserialize($content, $dataType, []),
+            $response->getStatusCode(),
+            $response->getHeaders()
+        ];
+    }
+
+    private function responseWithinRangeCode(
+        string $rangeCode,
+        int $statusCode
+    ): bool {
+        $left = (int) ($rangeCode[0].'00');
+        $right = (int) ($rangeCode[0].'99');
+
+        return $statusCode >= $left && $statusCode <= $right;
+    }
+}

+ 409 - 0
api-test/client/lib/Model/PostApiV3MarkupPreviews200Response.php

@@ -0,0 +1,409 @@
+<?php
+/**
+ * PostApiV3MarkupPreviews200Response
+ *
+ * PHP version 8.1
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ */
+
+/**
+ * MINT API
+ *
+ * International Academy Of Pali Tipitaka(国际巴利三藏学院)  由 `php openapi/scripts/generate.php` 依据 api-v13 的路由与控制器源码生成。 响应统一封装为 `{ok, message, data}`;`ok=false` 时 `message` 为错误信息。
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * Generated by: https://openapi-generator.tech
+ * Generator version: 7.25.0
+ */
+
+/**
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+namespace WikipaliApi\Model;
+
+use \ArrayAccess;
+use \WikipaliApi\ObjectSerializer;
+
+/**
+ * PostApiV3MarkupPreviews200Response Class Doc Comment
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ * @implements \ArrayAccess<string, mixed>
+ */
+class PostApiV3MarkupPreviews200Response implements ModelInterface, ArrayAccess, \JsonSerializable
+{
+    public const DISCRIMINATOR = null;
+
+    /**
+     * The original name of the model.
+     *
+     * @var string
+     */
+    protected static $openAPIModelName = 'post_api_v3_markup_previews_200_response';
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @var string[]
+     */
+    protected static $openAPITypes = [
+        'data' => '\WikipaliApi\Model\PostApiV3MarkupPreviews200ResponseData'
+    ];
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @var string[]
+     * @phpstan-var array<string, string|null>
+     * @psalm-var array<string, string|null>
+     */
+    protected static $openAPIFormats = [
+        'data' => null
+    ];
+
+    /**
+     * Array of nullable properties. Used for (de)serialization
+     *
+     * @var boolean[]
+     */
+    protected static array $openAPINullables = [
+        'data' => false
+    ];
+
+    /**
+     * If a nullable field gets set to null, insert it here
+     *
+     * @var boolean[]
+     */
+    protected array $openAPINullablesSetToNull = [];
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPITypes()
+    {
+        return self::$openAPITypes;
+    }
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPIFormats()
+    {
+        return self::$openAPIFormats;
+    }
+
+    /**
+     * Array of nullable properties
+     *
+     * @return array
+     */
+    protected static function openAPINullables(): array
+    {
+        return self::$openAPINullables;
+    }
+
+    /**
+     * Array of nullable field names deliberately set to null
+     *
+     * @return boolean[]
+     */
+    private function getOpenAPINullablesSetToNull(): array
+    {
+        return $this->openAPINullablesSetToNull;
+    }
+
+    /**
+     * Setter - Array of nullable field names deliberately set to null
+     *
+     * @param boolean[] $openAPINullablesSetToNull
+     */
+    private function setOpenAPINullablesSetToNull(array $openAPINullablesSetToNull): void
+    {
+        $this->openAPINullablesSetToNull = $openAPINullablesSetToNull;
+    }
+
+    /**
+     * Checks if a property is nullable
+     *
+     * @param string $property
+     * @return bool
+     */
+    public static function isNullable(string $property): bool
+    {
+        return self::openAPINullables()[$property] ?? false;
+    }
+
+    /**
+     * Checks if a nullable property is set to null.
+     *
+     * @param string $property
+     * @return bool
+     */
+    public function isNullableSetToNull(string $property): bool
+    {
+        return in_array($property, $this->getOpenAPINullablesSetToNull(), true);
+    }
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @var string[]
+     */
+    protected static $attributeMap = [
+        'data' => 'data'
+    ];
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @var string[]
+     */
+    protected static $setters = [
+        'data' => 'setData'
+    ];
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @var string[]
+     */
+    protected static $getters = [
+        'data' => 'getData'
+    ];
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @return array
+     */
+    public static function attributeMap()
+    {
+        return self::$attributeMap;
+    }
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @return array
+     */
+    public static function setters()
+    {
+        return self::$setters;
+    }
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @return array
+     */
+    public static function getters()
+    {
+        return self::$getters;
+    }
+
+    /**
+     * The original name of the model.
+     *
+     * @return string
+     */
+    public function getModelName()
+    {
+        return self::$openAPIModelName;
+    }
+
+
+    /**
+     * Associative array for storing property values
+     *
+     * @var mixed[]
+     */
+    protected $container = [];
+
+    /**
+     * Constructor
+     *
+     * @param mixed[]|null $data Associated array of property values
+     *                      initializing the model
+     */
+    public function __construct(?array $data = null)
+    {
+        $this->setIfExists('data', $data ?? [], null);
+    }
+
+    /**
+     * Sets $this->container[$variableName] to the given data or to the given default Value; if $variableName
+     * is nullable and its value is set to null in the $fields array, then mark it as "set to null" in the
+     * $this->openAPINullablesSetToNull array
+     *
+     * @param string $variableName
+     * @param array  $fields
+     * @param mixed  $defaultValue
+     */
+    private function setIfExists(string $variableName, array $fields, $defaultValue): void
+    {
+        if (self::isNullable($variableName) && array_key_exists($variableName, $fields) && is_null($fields[$variableName])) {
+            $this->openAPINullablesSetToNull[] = $variableName;
+        }
+
+        $this->container[$variableName] = $fields[$variableName] ?? $defaultValue;
+    }
+
+    /**
+     * Show all the invalid properties with reasons.
+     *
+     * @return array invalid properties with reasons
+     */
+    public function listInvalidProperties()
+    {
+        $invalidProperties = [];
+
+        return $invalidProperties;
+    }
+
+    /**
+     * Validate all the properties in the model
+     * return true if all passed
+     *
+     * @return bool True if all properties are valid
+     */
+    public function valid()
+    {
+        return count($this->listInvalidProperties()) === 0;
+    }
+
+
+    /**
+     * Gets data
+     *
+     * @return \WikipaliApi\Model\PostApiV3MarkupPreviews200ResponseData|null
+     */
+    public function getData()
+    {
+        return $this->container['data'];
+    }
+
+    /**
+     * Sets data
+     *
+     * @param \WikipaliApi\Model\PostApiV3MarkupPreviews200ResponseData|null $data data
+     *
+     * @return self
+     */
+    public function setData($data)
+    {
+        if (is_null($data)) {
+            throw new \InvalidArgumentException('non-nullable data cannot be null');
+        }
+        $this->container['data'] = $data;
+
+        return $this;
+    }
+    /**
+     * Returns true if offset exists. False otherwise.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return boolean
+     */
+    public function offsetExists(mixed $offset): bool
+    {
+        return isset($this->container[$offset]);
+    }
+
+    /**
+     * Gets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return mixed|null
+     */
+    #[\ReturnTypeWillChange]
+    public function offsetGet(mixed $offset)
+    {
+        return $this->container[$offset] ?? null;
+    }
+
+    /**
+     * Sets value based on offset.
+     *
+     * @param int|null $offset Offset
+     * @param mixed    $value  Value to be set
+     *
+     * @return void
+     */
+    public function offsetSet($offset, $value): void
+    {
+        if (is_null($offset)) {
+            $this->container[] = $value;
+        } else {
+            $this->container[$offset] = $value;
+        }
+    }
+
+    /**
+     * Unsets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return void
+     */
+    public function offsetUnset(mixed $offset): void
+    {
+        unset($this->container[$offset]);
+    }
+
+    /**
+     * Serializes the object to a value that can be serialized natively by json_encode().
+     * @link https://www.php.net/manual/en/jsonserializable.jsonserialize.php
+     *
+     * @return mixed Returns data which can be serialized by json_encode(), which is a value
+     * of any type other than a resource.
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+       return ObjectSerializer::sanitizeForSerialization($this);
+    }
+
+    /**
+     * Gets the string presentation of the object
+     *
+     * @return string
+     */
+    public function __toString()
+    {
+        return json_encode(
+            ObjectSerializer::sanitizeForSerialization($this),
+            JSON_PRETTY_PRINT
+        );
+    }
+
+    /**
+     * Gets a header-safe presentation of the object
+     *
+     * @return string
+     */
+    public function toHeaderValue()
+    {
+        return json_encode(ObjectSerializer::sanitizeForSerialization($this));
+    }
+}
+
+

+ 409 - 0
api-test/client/lib/Model/PostApiV3MarkupPreviews200ResponseData.php

@@ -0,0 +1,409 @@
+<?php
+/**
+ * PostApiV3MarkupPreviews200ResponseData
+ *
+ * PHP version 8.1
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ */
+
+/**
+ * MINT API
+ *
+ * International Academy Of Pali Tipitaka(国际巴利三藏学院)  由 `php openapi/scripts/generate.php` 依据 api-v13 的路由与控制器源码生成。 响应统一封装为 `{ok, message, data}`;`ok=false` 时 `message` 为错误信息。
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * Generated by: https://openapi-generator.tech
+ * Generator version: 7.25.0
+ */
+
+/**
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+namespace WikipaliApi\Model;
+
+use \ArrayAccess;
+use \WikipaliApi\ObjectSerializer;
+
+/**
+ * PostApiV3MarkupPreviews200ResponseData Class Doc Comment
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ * @implements \ArrayAccess<string, mixed>
+ */
+class PostApiV3MarkupPreviews200ResponseData implements ModelInterface, ArrayAccess, \JsonSerializable
+{
+    public const DISCRIMINATOR = null;
+
+    /**
+     * The original name of the model.
+     *
+     * @var string
+     */
+    protected static $openAPIModelName = 'post_api_v3_markup_previews_200_response_data';
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @var string[]
+     */
+    protected static $openAPITypes = [
+        'body' => '\WikipaliApi\Model\MarkupNode[]'
+    ];
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @var string[]
+     * @phpstan-var array<string, string|null>
+     * @psalm-var array<string, string|null>
+     */
+    protected static $openAPIFormats = [
+        'body' => null
+    ];
+
+    /**
+     * Array of nullable properties. Used for (de)serialization
+     *
+     * @var boolean[]
+     */
+    protected static array $openAPINullables = [
+        'body' => false
+    ];
+
+    /**
+     * If a nullable field gets set to null, insert it here
+     *
+     * @var boolean[]
+     */
+    protected array $openAPINullablesSetToNull = [];
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPITypes()
+    {
+        return self::$openAPITypes;
+    }
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPIFormats()
+    {
+        return self::$openAPIFormats;
+    }
+
+    /**
+     * Array of nullable properties
+     *
+     * @return array
+     */
+    protected static function openAPINullables(): array
+    {
+        return self::$openAPINullables;
+    }
+
+    /**
+     * Array of nullable field names deliberately set to null
+     *
+     * @return boolean[]
+     */
+    private function getOpenAPINullablesSetToNull(): array
+    {
+        return $this->openAPINullablesSetToNull;
+    }
+
+    /**
+     * Setter - Array of nullable field names deliberately set to null
+     *
+     * @param boolean[] $openAPINullablesSetToNull
+     */
+    private function setOpenAPINullablesSetToNull(array $openAPINullablesSetToNull): void
+    {
+        $this->openAPINullablesSetToNull = $openAPINullablesSetToNull;
+    }
+
+    /**
+     * Checks if a property is nullable
+     *
+     * @param string $property
+     * @return bool
+     */
+    public static function isNullable(string $property): bool
+    {
+        return self::openAPINullables()[$property] ?? false;
+    }
+
+    /**
+     * Checks if a nullable property is set to null.
+     *
+     * @param string $property
+     * @return bool
+     */
+    public function isNullableSetToNull(string $property): bool
+    {
+        return in_array($property, $this->getOpenAPINullablesSetToNull(), true);
+    }
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @var string[]
+     */
+    protected static $attributeMap = [
+        'body' => 'body'
+    ];
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @var string[]
+     */
+    protected static $setters = [
+        'body' => 'setBody'
+    ];
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @var string[]
+     */
+    protected static $getters = [
+        'body' => 'getBody'
+    ];
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @return array
+     */
+    public static function attributeMap()
+    {
+        return self::$attributeMap;
+    }
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @return array
+     */
+    public static function setters()
+    {
+        return self::$setters;
+    }
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @return array
+     */
+    public static function getters()
+    {
+        return self::$getters;
+    }
+
+    /**
+     * The original name of the model.
+     *
+     * @return string
+     */
+    public function getModelName()
+    {
+        return self::$openAPIModelName;
+    }
+
+
+    /**
+     * Associative array for storing property values
+     *
+     * @var mixed[]
+     */
+    protected $container = [];
+
+    /**
+     * Constructor
+     *
+     * @param mixed[]|null $data Associated array of property values
+     *                      initializing the model
+     */
+    public function __construct(?array $data = null)
+    {
+        $this->setIfExists('body', $data ?? [], null);
+    }
+
+    /**
+     * Sets $this->container[$variableName] to the given data or to the given default Value; if $variableName
+     * is nullable and its value is set to null in the $fields array, then mark it as "set to null" in the
+     * $this->openAPINullablesSetToNull array
+     *
+     * @param string $variableName
+     * @param array  $fields
+     * @param mixed  $defaultValue
+     */
+    private function setIfExists(string $variableName, array $fields, $defaultValue): void
+    {
+        if (self::isNullable($variableName) && array_key_exists($variableName, $fields) && is_null($fields[$variableName])) {
+            $this->openAPINullablesSetToNull[] = $variableName;
+        }
+
+        $this->container[$variableName] = $fields[$variableName] ?? $defaultValue;
+    }
+
+    /**
+     * Show all the invalid properties with reasons.
+     *
+     * @return array invalid properties with reasons
+     */
+    public function listInvalidProperties()
+    {
+        $invalidProperties = [];
+
+        return $invalidProperties;
+    }
+
+    /**
+     * Validate all the properties in the model
+     * return true if all passed
+     *
+     * @return bool True if all properties are valid
+     */
+    public function valid()
+    {
+        return count($this->listInvalidProperties()) === 0;
+    }
+
+
+    /**
+     * Gets body
+     *
+     * @return \WikipaliApi\Model\MarkupNode[]|null
+     */
+    public function getBody()
+    {
+        return $this->container['body'];
+    }
+
+    /**
+     * Sets body
+     *
+     * @param \WikipaliApi\Model\MarkupNode[]|null $body body
+     *
+     * @return self
+     */
+    public function setBody($body)
+    {
+        if (is_null($body)) {
+            throw new \InvalidArgumentException('non-nullable body cannot be null');
+        }
+        $this->container['body'] = $body;
+
+        return $this;
+    }
+    /**
+     * Returns true if offset exists. False otherwise.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return boolean
+     */
+    public function offsetExists(mixed $offset): bool
+    {
+        return isset($this->container[$offset]);
+    }
+
+    /**
+     * Gets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return mixed|null
+     */
+    #[\ReturnTypeWillChange]
+    public function offsetGet(mixed $offset)
+    {
+        return $this->container[$offset] ?? null;
+    }
+
+    /**
+     * Sets value based on offset.
+     *
+     * @param int|null $offset Offset
+     * @param mixed    $value  Value to be set
+     *
+     * @return void
+     */
+    public function offsetSet($offset, $value): void
+    {
+        if (is_null($offset)) {
+            $this->container[] = $value;
+        } else {
+            $this->container[$offset] = $value;
+        }
+    }
+
+    /**
+     * Unsets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return void
+     */
+    public function offsetUnset(mixed $offset): void
+    {
+        unset($this->container[$offset]);
+    }
+
+    /**
+     * Serializes the object to a value that can be serialized natively by json_encode().
+     * @link https://www.php.net/manual/en/jsonserializable.jsonserialize.php
+     *
+     * @return mixed Returns data which can be serialized by json_encode(), which is a value
+     * of any type other than a resource.
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+       return ObjectSerializer::sanitizeForSerialization($this);
+    }
+
+    /**
+     * Gets the string presentation of the object
+     *
+     * @return string
+     */
+    public function __toString()
+    {
+        return json_encode(
+            ObjectSerializer::sanitizeForSerialization($this),
+            JSON_PRETTY_PRINT
+        );
+    }
+
+    /**
+     * Gets a header-safe presentation of the object
+     *
+     * @return string
+     */
+    public function toHeaderValue()
+    {
+        return json_encode(ObjectSerializer::sanitizeForSerialization($this));
+    }
+}
+
+

+ 548 - 0
api-test/client/lib/Model/PostApiV3MarkupPreviewsRequest.php

@@ -0,0 +1,548 @@
+<?php
+/**
+ * PostApiV3MarkupPreviewsRequest
+ *
+ * PHP version 8.1
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ */
+
+/**
+ * MINT API
+ *
+ * International Academy Of Pali Tipitaka(国际巴利三藏学院)  由 `php openapi/scripts/generate.php` 依据 api-v13 的路由与控制器源码生成。 响应统一封装为 `{ok, message, data}`;`ok=false` 时 `message` 为错误信息。
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * Generated by: https://openapi-generator.tech
+ * Generator version: 7.25.0
+ */
+
+/**
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+namespace WikipaliApi\Model;
+
+use \ArrayAccess;
+use \WikipaliApi\ObjectSerializer;
+
+/**
+ * PostApiV3MarkupPreviewsRequest Class Doc Comment
+ *
+ * @category Class
+ * @package  WikipaliApi
+ * @author   OpenAPI Generator team
+ * @link     https://openapi-generator.tech
+ * @implements \ArrayAccess<string, mixed>
+ */
+class PostApiV3MarkupPreviewsRequest implements ModelInterface, ArrayAccess, \JsonSerializable
+{
+    public const DISCRIMINATOR = null;
+
+    /**
+     * The original name of the model.
+     *
+     * @var string
+     */
+    protected static $openAPIModelName = 'post_api_v3_markup_previews_request';
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @var string[]
+     */
+    protected static $openAPITypes = [
+        'content' => 'string',
+        'content_type' => 'string',
+        'channels' => 'string[]',
+        'lang' => 'string'
+    ];
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @var string[]
+     * @phpstan-var array<string, string|null>
+     * @psalm-var array<string, string|null>
+     */
+    protected static $openAPIFormats = [
+        'content' => null,
+        'content_type' => null,
+        'channels' => null,
+        'lang' => null
+    ];
+
+    /**
+     * Array of nullable properties. Used for (de)serialization
+     *
+     * @var boolean[]
+     */
+    protected static array $openAPINullables = [
+        'content' => false,
+        'content_type' => false,
+        'channels' => false,
+        'lang' => false
+    ];
+
+    /**
+     * If a nullable field gets set to null, insert it here
+     *
+     * @var boolean[]
+     */
+    protected array $openAPINullablesSetToNull = [];
+
+    /**
+     * Array of property to type mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPITypes()
+    {
+        return self::$openAPITypes;
+    }
+
+    /**
+     * Array of property to format mappings. Used for (de)serialization
+     *
+     * @return array
+     */
+    public static function openAPIFormats()
+    {
+        return self::$openAPIFormats;
+    }
+
+    /**
+     * Array of nullable properties
+     *
+     * @return array
+     */
+    protected static function openAPINullables(): array
+    {
+        return self::$openAPINullables;
+    }
+
+    /**
+     * Array of nullable field names deliberately set to null
+     *
+     * @return boolean[]
+     */
+    private function getOpenAPINullablesSetToNull(): array
+    {
+        return $this->openAPINullablesSetToNull;
+    }
+
+    /**
+     * Setter - Array of nullable field names deliberately set to null
+     *
+     * @param boolean[] $openAPINullablesSetToNull
+     */
+    private function setOpenAPINullablesSetToNull(array $openAPINullablesSetToNull): void
+    {
+        $this->openAPINullablesSetToNull = $openAPINullablesSetToNull;
+    }
+
+    /**
+     * Checks if a property is nullable
+     *
+     * @param string $property
+     * @return bool
+     */
+    public static function isNullable(string $property): bool
+    {
+        return self::openAPINullables()[$property] ?? false;
+    }
+
+    /**
+     * Checks if a nullable property is set to null.
+     *
+     * @param string $property
+     * @return bool
+     */
+    public function isNullableSetToNull(string $property): bool
+    {
+        return in_array($property, $this->getOpenAPINullablesSetToNull(), true);
+    }
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @var string[]
+     */
+    protected static $attributeMap = [
+        'content' => 'content',
+        'content_type' => 'content_type',
+        'channels' => 'channels',
+        'lang' => 'lang'
+    ];
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @var string[]
+     */
+    protected static $setters = [
+        'content' => 'setContent',
+        'content_type' => 'setContentType',
+        'channels' => 'setChannels',
+        'lang' => 'setLang'
+    ];
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @var string[]
+     */
+    protected static $getters = [
+        'content' => 'getContent',
+        'content_type' => 'getContentType',
+        'channels' => 'getChannels',
+        'lang' => 'getLang'
+    ];
+
+    /**
+     * Array of attributes where the key is the local name,
+     * and the value is the original name
+     *
+     * @return array
+     */
+    public static function attributeMap()
+    {
+        return self::$attributeMap;
+    }
+
+    /**
+     * Array of attributes to setter functions (for deserialization of responses)
+     *
+     * @return array
+     */
+    public static function setters()
+    {
+        return self::$setters;
+    }
+
+    /**
+     * Array of attributes to getter functions (for serialization of requests)
+     *
+     * @return array
+     */
+    public static function getters()
+    {
+        return self::$getters;
+    }
+
+    /**
+     * The original name of the model.
+     *
+     * @return string
+     */
+    public function getModelName()
+    {
+        return self::$openAPIModelName;
+    }
+
+    public const CONTENT_TYPE_MARKDOWN = 'markdown';
+    public const CONTENT_TYPE_MARKDOWN_E2 = 'markdown-e2';
+
+    /**
+     * Gets allowable values of the enum
+     *
+     * @return string[]
+     */
+    public function getContentTypeAllowableValues()
+    {
+        return [
+            self::CONTENT_TYPE_MARKDOWN,
+            self::CONTENT_TYPE_MARKDOWN_E2,
+        ];
+    }
+
+    /**
+     * Associative array for storing property values
+     *
+     * @var mixed[]
+     */
+    protected $container = [];
+
+    /**
+     * Constructor
+     *
+     * @param mixed[]|null $data Associated array of property values
+     *                      initializing the model
+     */
+    public function __construct(?array $data = null)
+    {
+        $this->setIfExists('content', $data ?? [], null);
+        $this->setIfExists('content_type', $data ?? [], 'markdown');
+        $this->setIfExists('channels', $data ?? [], null);
+        $this->setIfExists('lang', $data ?? [], null);
+    }
+
+    /**
+     * Sets $this->container[$variableName] to the given data or to the given default Value; if $variableName
+     * is nullable and its value is set to null in the $fields array, then mark it as "set to null" in the
+     * $this->openAPINullablesSetToNull array
+     *
+     * @param string $variableName
+     * @param array  $fields
+     * @param mixed  $defaultValue
+     */
+    private function setIfExists(string $variableName, array $fields, $defaultValue): void
+    {
+        if (self::isNullable($variableName) && array_key_exists($variableName, $fields) && is_null($fields[$variableName])) {
+            $this->openAPINullablesSetToNull[] = $variableName;
+        }
+
+        $this->container[$variableName] = $fields[$variableName] ?? $defaultValue;
+    }
+
+    /**
+     * Show all the invalid properties with reasons.
+     *
+     * @return array invalid properties with reasons
+     */
+    public function listInvalidProperties()
+    {
+        $invalidProperties = [];
+
+        if ($this->container['content'] === null) {
+            $invalidProperties[] = "'content' can't be null";
+        }
+        $allowedValues = $this->getContentTypeAllowableValues();
+        if (!is_null($this->container['content_type']) && !in_array($this->container['content_type'], $allowedValues, true)) {
+            $invalidProperties[] = sprintf(
+                "invalid value '%s' for 'content_type', must be one of '%s'",
+                $this->container['content_type'],
+                implode("', '", $allowedValues)
+            );
+        }
+
+        return $invalidProperties;
+    }
+
+    /**
+     * Validate all the properties in the model
+     * return true if all passed
+     *
+     * @return bool True if all properties are valid
+     */
+    public function valid()
+    {
+        return count($this->listInvalidProperties()) === 0;
+    }
+
+
+    /**
+     * Gets content
+     *
+     * @return string
+     */
+    public function getContent()
+    {
+        return $this->container['content'];
+    }
+
+    /**
+     * Sets content
+     *
+     * @param string $content 源码,最多 20000 字
+     *
+     * @return self
+     */
+    public function setContent($content)
+    {
+        if (is_null($content)) {
+            throw new \InvalidArgumentException('non-nullable content cannot be null');
+        }
+        $this->container['content'] = $content;
+
+        return $this;
+    }
+
+    /**
+     * Gets content_type
+     *
+     * @return string|null
+     */
+    public function getContentType()
+    {
+        return $this->container['content_type'];
+    }
+
+    /**
+     * Sets content_type
+     *
+     * @param string|null $content_type 方言
+     *
+     * @return self
+     */
+    public function setContentType($content_type)
+    {
+        if (is_null($content_type)) {
+            throw new \InvalidArgumentException('non-nullable content_type cannot be null');
+        }
+        $allowedValues = $this->getContentTypeAllowableValues();
+        if (!in_array($content_type, $allowedValues, true)) {
+            throw new \InvalidArgumentException(
+                sprintf(
+                    "Invalid value '%s' for 'content_type', must be one of '%s'",
+                    $content_type,
+                    implode("', '", $allowedValues)
+                )
+            );
+        }
+        $this->container['content_type'] = $content_type;
+
+        return $this;
+    }
+
+    /**
+     * Gets channels
+     *
+     * @return string[]|null
+     */
+    public function getChannels()
+    {
+        return $this->container['channels'];
+    }
+
+    /**
+     * Sets channels
+     *
+     * @param string[]|null $channels 内容所属的 channel uid,最多 10 个
+     *
+     * @return self
+     */
+    public function setChannels($channels)
+    {
+        if (is_null($channels)) {
+            throw new \InvalidArgumentException('non-nullable channels cannot be null');
+        }
+        $this->container['channels'] = $channels;
+
+        return $this;
+    }
+
+    /**
+     * Gets lang
+     *
+     * @return string|null
+     */
+    public function getLang()
+    {
+        return $this->container['lang'];
+    }
+
+    /**
+     * Sets lang
+     *
+     * @param string|null $lang 没给 channel 时用的语言,如 zh-Hans。缺省用界面语言(Accept-Language 协商的结果)
+     *
+     * @return self
+     */
+    public function setLang($lang)
+    {
+        if (is_null($lang)) {
+            throw new \InvalidArgumentException('non-nullable lang cannot be null');
+        }
+        $this->container['lang'] = $lang;
+
+        return $this;
+    }
+    /**
+     * Returns true if offset exists. False otherwise.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return boolean
+     */
+    public function offsetExists(mixed $offset): bool
+    {
+        return isset($this->container[$offset]);
+    }
+
+    /**
+     * Gets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return mixed|null
+     */
+    #[\ReturnTypeWillChange]
+    public function offsetGet(mixed $offset)
+    {
+        return $this->container[$offset] ?? null;
+    }
+
+    /**
+     * Sets value based on offset.
+     *
+     * @param int|null $offset Offset
+     * @param mixed    $value  Value to be set
+     *
+     * @return void
+     */
+    public function offsetSet($offset, $value): void
+    {
+        if (is_null($offset)) {
+            $this->container[] = $value;
+        } else {
+            $this->container[$offset] = $value;
+        }
+    }
+
+    /**
+     * Unsets offset.
+     *
+     * @param integer|string $offset Offset
+     *
+     * @return void
+     */
+    public function offsetUnset(mixed $offset): void
+    {
+        unset($this->container[$offset]);
+    }
+
+    /**
+     * Serializes the object to a value that can be serialized natively by json_encode().
+     * @link https://www.php.net/manual/en/jsonserializable.jsonserialize.php
+     *
+     * @return mixed Returns data which can be serialized by json_encode(), which is a value
+     * of any type other than a resource.
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+       return ObjectSerializer::sanitizeForSerialization($this);
+    }
+
+    /**
+     * Gets the string presentation of the object
+     *
+     * @return string
+     */
+    public function __toString()
+    {
+        return json_encode(
+            ObjectSerializer::sanitizeForSerialization($this),
+            JSON_PRETTY_PRINT
+        );
+    }
+
+    /**
+     * Gets a header-safe presentation of the object
+     *
+     * @return string
+     */
+    public function toHeaderValue()
+    {
+        return json_encode(ObjectSerializer::sanitizeForSerialization($this));
+    }
+}
+
+

+ 46 - 0
api-v13/app/Http/Controllers/V3/MarkupPreviewController.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace App\Http\Controllers\V3;
+
+use App\Http\Controllers\Concerns\ResolvesCurrentUser;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\V3\StoreMarkupPreviewRequest;
+use App\Http\Resources\V3\MarkupPreviewResource;
+use App\Services\V3\MarkupPreviewService;
+
+/**
+ * 源码预览(模板生成器、编辑器的「预览」)。
+ *
+ * 新能力,没有一一对应的 v2 端点:v2 只有绑定在某篇文章上、走旧渲染器的 `PUT /v2/article-preview/{id}`
+ * (`ArticleController@preview`),那份在 dashboard-v4 下线前原样保留,不要改动。
+ */
+class MarkupPreviewController extends Controller
+{
+    use ResolvesCurrentUser;
+
+    public function __construct(private readonly MarkupPreviewService $previews) {}
+
+    /**
+     * 预览一段源码
+     *
+     * 把还没保存的 markdown 渲染成节点树(与术语、批注的 `body` 同形),不写库,所以是 200 而不是 201。
+     * 口径同阅读页的读模式:术语按第一个 channel 查,句子模板缺省读这些 channel 的译文。
+     * 给了 `channels` 的,每个都要有读权限:不存在 404,看不见 403。
+     *
+     * @bodyParam content string required 源码,最多 20000 字
+     * @bodyParam content_type string 方言。Enum: markdown, markdown-e2。Default: markdown
+     * @bodyParam channels string[] 内容所属的 channel uid,最多 10 个
+     * @bodyParam lang string 没给 channel 时用的语言,如 zh-Hans。缺省用界面语言(Accept-Language 协商的结果)
+     *
+     * @responseStatus 403 给的 channel 没有读权限
+     * @responseStatus 404 给的 channel 不存在
+     */
+    public function __invoke(StoreMarkupPreviewRequest $request)
+    {
+        return MarkupPreviewResource::make($this->previews->preview(
+            $request->validated(),
+            $this->currentUser($request)['user_uid'],
+            app()->getLocale(),
+        ));
+    }
+}

+ 30 - 0
api-v13/app/Http/Requests/V3/StoreMarkupPreviewRequest.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Http\Requests\V3;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+/**
+ * `POST /v3/markup-previews`:要预览的源码与渲染口径。
+ */
+class StoreMarkupPreviewRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, array<int, mixed>>
+     */
+    public function rules(): array
+    {
+        return [
+            'content' => ['required', 'string', 'max:20000'],
+            'content_type' => ['sometimes', 'string', 'in:markdown,markdown-e2'],
+            'channels' => ['sometimes', 'array', 'max:10'],
+            'channels.*' => ['uuid'],
+            'lang' => ['sometimes', 'string', 'max:16', 'regex:/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/'],
+        ];
+    }
+}

+ 20 - 0
api-v13/app/Http/Resources/V3/MarkupPreviewResource.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace App\Http\Resources\V3;
+
+use App\Services\V3\MarkupPreviewService;
+use Illuminate\Http\Request;
+
+/**
+ * 源码预览结果({@see MarkupPreviewService}):`body` 是新渲染器的节点树,与术语、批注的 `body` 同形。
+ */
+class MarkupPreviewResource extends BaseResource
+{
+    /**
+     * @return array{body: list<MarkupNode>}
+     */
+    public function toArray(Request $request): array
+    {
+        return $this->resource;
+    }
+}

+ 47 - 0
api-v13/app/Services/V3/MarkupPreviewService.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace App\Services\V3;
+
+use App\Services\Markup\MarkupService;
+use App\Services\Markup\RenderOptions;
+use Illuminate\Auth\Access\AuthorizationException;
+
+/**
+ * 源码预览:把一段还没保存的 markdown(模板生成器、编辑器里写到一半的内容)渲染成节点树。
+ *
+ * 渲染口径与保存后的阅读页相同({@see MarkupService},读模式)。
+ */
+class MarkupPreviewService
+{
+    public function __construct(
+        private readonly MarkupService $markup,
+        private readonly ChannelAbilityService $channels,
+    ) {}
+
+    /**
+     * 给了 channels 的,每个都要看得见(不存在 404、看不见 403),否则就能借预览读私有 channel 的译文。
+     *
+     * FIXME: 源码里模板自带的 channel(`{{sent|…|channel=…}}`、`{{65-464-2-27@channel}}`)在渲染器内部取数,
+     * 这里拦不到;SentenceLoader 不判可见性,存量的术语 / 批注正文也有同样的口子,要在 Markup 的取数层统一补。
+     *
+     * @param  array{content: string, content_type?: string, channels?: list<string>, lang?: string}  $input
+     * @return array{body: list<array<string, mixed>>}
+     *
+     * @throws AuthorizationException
+     */
+    public function preview(array $input, string $userUid, string $defaultLang): array
+    {
+        $channels = array_values(array_unique($input['channels'] ?? []));
+        foreach ($channels as $channel) {
+            $this->channels->assertReadable($channel, $userUid);
+        }
+
+        $body = $this->markup->render($input['content'], new RenderOptions(
+            channels: $channels,
+            contentType: $input['content_type'] ?? 'markdown',
+            lang: $input['lang'] ?? $defaultLang,
+        ));
+
+        return ['body' => is_array($body) ? $body : []];
+    }
+}

+ 1 - 0
api-v13/routes/api.php

@@ -356,6 +356,7 @@ Route::prefix('v3')->as('v3.')->middleware(NegotiateLocale::class)->group(functi
     require __DIR__.'/v3/channel.php';
     require __DIR__.'/v3/channel.php';
     require __DIR__.'/v3/term.php';
     require __DIR__.'/v3/term.php';
     require __DIR__.'/v3/nissaya.php';
     require __DIR__.'/v3/nissaya.php';
+    require __DIR__.'/v3/markup.php';
     require __DIR__.'/v3/group.php';
     require __DIR__.'/v3/group.php';
     require __DIR__.'/v3/interaction.php';
     require __DIR__.'/v3/interaction.php';
     require __DIR__.'/v3/auth.php';
     require __DIR__.'/v3/auth.php';

+ 16 - 0
api-v13/routes/v3/markup.php

@@ -0,0 +1,16 @@
+<?php
+
+/*
+|--------------------------------------------------------------------------
+| v3 · markup —— 正文源码的渲染
+|--------------------------------------------------------------------------
+|
+| 由 routes/api.php 的 v3 组 require 进来,前缀已在那边加好。
+|
+*/
+
+use App\Http\Controllers\V3\MarkupPreviewController;
+use Illuminate\Support\Facades\Route;
+
+// 源码预览:不写库,要登录
+Route::post('markup-previews', MarkupPreviewController::class)->middleware('auth.v3')->name('markup-previews.store');

+ 64 - 0
api-v13/tests/Feature/MarkupPreviewV3Test.php

@@ -0,0 +1,64 @@
+<?php
+
+use App\Models\Channel;
+use App\Models\DhammaTerm;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Str;
+
+uses(RefreshDatabase::class);
+
+/*
+ * POST /v3/markup-previews:把还没保存的源码渲染成节点树(模板生成器的预览)。
+ * 这里断言的是形状而非契约(spectator 未安装,见 v3-resource skill 第 3 步)。
+ */
+
+beforeEach(function () {
+    $this->me = makeStudio('preview-me');
+    $this->channel = makeChannel($this->me, 'preview channel');
+});
+
+it('renders the source into a node tree, resolving templates against the given channel', function () {
+    (new DhammaTerm)->forceFill([
+        'id' => random_int(1, PHP_INT_MAX), 'guid' => (string) Str::uuid(), 'word' => 'dhamma', 'word_en' => 'dhamma',
+        'meaning' => '法', 'language' => 'zh-Hans', 'channal' => $this->channel, 'owner' => $this->me,
+        'editor_id' => 0, 'create_time' => time() * 1000, 'modify_time' => time() * 1000,
+    ])->save();
+
+    $body = $this->postJson('/api/v3/markup-previews', [
+        'content' => '{{term|dhamma}}',
+        'channels' => [$this->channel],
+    ], authHeader($this->me))->assertOk()->json('data.body');
+
+    expect($body[0])->toMatchArray(['type' => 'tpl', 'name' => 'term'])
+        ->and($body[0]['props'])->toMatchArray(['word' => 'dhamma', 'meaning' => '法', 'channel' => $this->channel]);
+});
+
+it('renders without channels, and keeps unknown templates as their source', function () {
+    $body = $this->postJson('/api/v3/markup-previews', [
+        'content' => "{{v|url=https://example.com/a.mp4|style=card|title=视频}}\n\n{{nope|x}}",
+        'content_type' => 'markdown-e2',
+    ], authHeader($this->me))->assertOk()->json('data.body');
+
+    expect(json_encode($body))->toContain('"name":"video"')->toContain('"name":"unknown"');
+});
+
+it('requires login', function () {
+    $this->postJson('/api/v3/markup-previews', ['content' => 'x'])->assertUnauthorized();
+});
+
+it('rejects a missing content, a bad content type and a non-uuid channel', function () {
+    $this->postJson('/api/v3/markup-previews', [
+        'content_type' => 'html', 'channels' => ['nope'],
+    ], authHeader($this->me))->assertUnprocessable()->assertJsonValidationErrors(['content', 'content_type', 'channels.0']);
+});
+
+it('refuses a private channel the user cannot read, and 404s an unknown one', function () {
+    $other = makeStudio('preview-other');
+    $private = makeChannel($other, 'private channel');
+    Channel::where('uid', $private)->update(['status' => 10]);
+
+    $this->postJson('/api/v3/markup-previews', ['content' => 'x', 'channels' => [$private]], authHeader($this->me))
+        ->assertForbidden();
+    $this->postJson('/api/v3/markup-previews', ['content' => 'x', 'channels' => [(string) Str::uuid()]], authHeader($this->me))
+        ->assertNotFound();
+});

+ 85 - 0
dashboard-v6/src/api/schema.d.ts

@@ -8818,6 +8818,30 @@ export interface paths {
         patch?: never;
         patch?: never;
         trace?: never;
         trace?: never;
     };
     };
+    "/v3/markup-previews": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * 预览一段源码
+         * @description 把还没保存的 markdown 渲染成节点树(与术语、批注的 `body` 同形),不写库,所以是 200 而不是 201。
+         *     口径同阅读页的读模式:术语按第一个 channel 查,句子模板缺省读这些 channel 的译文。
+         *     给了 `channels` 的,每个都要有读权限:不存在 404,看不见 403。
+         *
+         *     实现:`V3\MarkupPreviewController@__invoke`
+         */
+        post: operations["post_api_v3_markup_previews"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v3/me": {
     "/v3/me": {
         parameters: {
         parameters: {
             query?: never;
             query?: never;
@@ -39952,6 +39976,67 @@ export interface operations {
             422: components["responses"]["ProblemValidation"];
             422: components["responses"]["ProblemValidation"];
         };
         };
     };
     };
+    post_api_v3_markup_previews: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description 源码,最多 20000 字 */
+                    content: string;
+                    /**
+                     * @description 方言
+                     * @default markdown
+                     * @enum {string}
+                     */
+                    content_type?: "markdown" | "markdown-e2";
+                    /** @description 内容所属的 channel uid,最多 10 个 */
+                    channels?: unknown[];
+                    /** @description 没给 channel 时用的语言,如 zh-Hans。缺省用界面语言(Accept-Language 协商的结果) */
+                    lang?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description 成功 */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            body?: components["schemas"]["MarkupNode"][];
+                        };
+                    };
+                };
+            };
+            401: components["responses"]["ProblemUnauthorized"];
+            /** @description 给的 channel 没有读权限 */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            /** @description 给的 channel 不存在 */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ProblemDetails"];
+                };
+            };
+            422: components["responses"]["ProblemValidation"];
+        };
+    };
     get_api_v3_me: {
     get_api_v3_me: {
         parameters: {
         parameters: {
             query?: never;
             query?: never;

+ 2 - 0
openapi/public/assets/protocol/main.yaml

@@ -833,6 +833,8 @@ paths:
     $ref: ./resources/auto/v3-invites.yaml
     $ref: ./resources/auto/v3-invites.yaml
   '/v3/invites/{invite}':
   '/v3/invites/{invite}':
     $ref: ./resources/auto/v3-invites-invite.yaml
     $ref: ./resources/auto/v3-invites-invite.yaml
+  /v3/markup-previews:
+    $ref: ./resources/auto/v3-markup-previews.yaml
   /v3/me:
   /v3/me:
     $ref: ./resources/auto/v3-me.yaml
     $ref: ./resources/auto/v3-me.yaml
   /v3/me/agent-threads:
   /v3/me/agent-threads:

+ 71 - 0
openapi/public/assets/protocol/resources/auto/v3-markup-previews.yaml

@@ -0,0 +1,71 @@
+# 由 openapi/scripts/generate.php 生成,请勿手改;补充写到 overrides/v3-markup-previews.yaml
+post:
+  summary: 预览一段源码
+  tags:
+    - markup-previews
+  operationId: post_api_v3_markup_previews
+  description: |-
+    把还没保存的 markdown 渲染成节点树(与术语、批注的 `body` 同形),不写库,所以是 200 而不是 201。
+    口径同阅读页的读模式:术语按第一个 channel 查,句子模板缺省读这些 channel 的译文。
+    给了 `channels` 的,每个都要有读权限:不存在 404,看不见 403。
+
+    实现:`V3\MarkupPreviewController@__invoke`
+  security:
+    -
+      bearerAuth: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            content:
+              type: string
+              description: '源码,最多 20000 字'
+            content_type:
+              type: string
+              description: 方言
+              enum:
+                - markdown
+                - markdown-e2
+              default: markdown
+            channels:
+              type: array
+              description: '内容所属的 channel uid,最多 10 个'
+            lang:
+              type: string
+              description: '没给 channel 时用的语言,如 zh-Hans。缺省用界面语言(Accept-Language 协商的结果)'
+          required:
+            - content
+  responses:
+    200:
+      description: 成功
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                type: object
+                properties:
+                  body:
+                    type: array
+                    items:
+                      $ref: '../../main.yaml#/components/schemas/MarkupNode'
+    401:
+      $ref: '../../main.yaml#/components/responses/ProblemUnauthorized'
+    403:
+      description: '给的 channel 没有读权限'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '../../main.yaml#/components/schemas/ProblemDetails'
+    404:
+      description: '给的 channel 不存在'
+      content:
+        application/problem+json:
+          schema:
+            $ref: '../../main.yaml#/components/schemas/ProblemDetails'
+    422:
+      $ref: '../../main.yaml#/components/responses/ProblemValidation'