Add a api document.

doc/yiwen-api.md

@@ -0,0 +1,35 @@
+# yiwen-api
+
+## 读取网页
+
+`GET https://api.yiwen.ltd/v1/scraping?url=encodedUrl`
+
+示例：
+```
+GET https://api.yiwen.ltd/v1/scraping?url=https%3A%2F%2Fmp.weixin.qq.com%2Fs%2F6iCpGzsqnXcGZPoEhqJE4Q
+Accept: application/json
+Cookie: YW_DID=ciqui8xxxx; YW_SESS=HFmzbngWbxxxxxWAkAk
+Authorization: Bearer hE2iAScESDIxxxxxxxeCMK
+```
+
+返回：
+```json
+{
+  "retry": 0,
+  "result": {
+    "id": "cis0vcgcert0052hqvbg",
+    "url": "https://mp.weixin.qq.com/s/6iCpGzsqnXcGZPoEhqJE4Q",
+    "src": "",
+    "title": "网络平台提供代币充值服务合规要点——以抖音抖币充值为例",
+    "meta": {
+      "og:article:author": "夏梦雅团队",
+      "og:description": "本文共4803字,预计阅读时长为20分钟",
+      "og:image": "https://mmbiz.qpic.cn/mmbiz_jpg/qjp6a5pznC2zfliaqxET0c8bia4gicA3BnMIb5dCNwGKTvTJPSpaicc4Ht920xH7MJlH9cLPA2RibcPyms1bjZ4g8GA/0?wx_fmt=jpeg",
+      "og:site_name": "Weixin Official Accounts Platform",
+      "og:type": "article",
+      "og:url": "http://mp.weixin.qq.com/s?__biz=MzU2NzgzODEzMw==\u0026mid=2247485848\u0026idx=1\u0026sn=f7dd03a96e23d92dff462f754d528a70\u0026chksm=fc965d42cbe1d45473de15cb435468bb97d106f3d4f3a980fb9a0067aeee07ec0e80e1ab1449#rd"
+    },
+    "content": "WVqUuQACZHR5cGVjZG9jZ2Nvb...base64_url_raw_encode_cbor...5ZCI6KeE6KaB54K54oCU4oCU"
+  }
+}
+```

doc/yiwen-api.yml

@@ -0,0 +1,103 @@
+openapi: '3.0.1'
+info:
+  title: Yiwen-API
+  version: 'v1'
+servers:
+  - url: https://api.yiwen.ltd
+tags:
+  - name: Scraping
+    description: 读取 web 文章内容
+  - name: Creation
+    description: 草稿、稿件
+  - name: Publication
+    description: 作品、出版物
+components:
+  securitySchemes:
+    CookieSession:
+      name: Session
+      type: apiKey
+      in: cookie
+    HeaderAuthorizationCWT:
+      type: http
+      scheme: bearer
+      bearerFormat: CWT
+  parameters:
+    QueryEncodedUrl:
+      name: url
+      in: query
+      required: true
+      description: ''
+      schema:
+        type: string
+  schemas:
+    ScrapingDocument:
+      type: object
+      properties:
+        id:
+          type: string
+          format: byte
+          description: Xid 对象，scraping id
+        url:
+          type: string
+          description: 经过服务器处理的 url
+        src:
+          type: string
+          description: 用户原始输入的 url
+        title:
+          type: string
+          description: 从 web 读取到的文章标题
+        meta:
+          type: object
+          description: 从 web 读取到的文章元数据，一般以 `og:` 为前缀
+        content:
+          type: string
+          format: byte
+          description: CBOR 格式的文章内容
+  responses:
+    ErrorResponse:
+      description: 标准错误返回结果
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+                description: 错误代号
+                example: NotFound
+              message:
+                type: string
+                description: 错误详情
+                example: some thing not found
+    ScrapingResponse:
+      description: 读取 web 文章的返回结果
+      content:
+        application/cbor:
+          schema:
+            type: object
+            properties:
+              result:
+                type: object
+                $ref: '#/components/schemas/ScrapingDocument'
+        application/json:
+          schema:
+            type: object
+            properties:
+              result:
+                type: object
+                $ref: '#/components/schemas/ScrapingDocument'
+paths:
+  /v1/scraping:
+    get:
+      tags:
+        - Scraping
+      summary: 获取指定 url 文章内容。
+      security:
+        - CookieSession: []
+        - HeaderAuthorizationCWT: []
+      parameters:
+        - $ref: '#/components/parameters/QueryEncodedUrl'
+      responses:
+        '200':
+          description: OK
+          $ref: '#/components/responses/ScrapingResponse'