{
  "openapi": "3.1.0",
  "info": {
    "title": "汉字怎么写 API",
    "summary": "Chinese character stroke-order API for learners and AI agents.",
    "description": "Free REST API for Chinese character writing data: pinyin, radical, stroke count, stroke names, common words, writing advice, and Hanzi Writer compatible stroke path data.",
    "version": "0.1.0"
  },
  "servers": [
    {
      "url": "https://wr.practice-hanzi.uk",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/hanzi": {
      "get": {
        "operationId": "getHanziWriting",
        "summary": "Get writing data for one Chinese character",
        "parameters": [
          {
            "name": "char",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1
            },
            "description": "One Chinese character, for example 学."
          }
        ],
        "responses": {
          "200": {
            "description": "Character writing data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HanziWriting"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/phrase": {
      "get": {
        "operationId": "getPhraseWriting",
        "summary": "Get writing data for a Chinese word or short phrase",
        "parameters": [
          {
            "name": "text",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 12
            },
            "description": "Chinese word or short phrase, for example 学习."
          }
        ],
        "responses": {
          "200": {
            "description": "Phrase writing data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PhraseWriting"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/hanzi/{char}/strokes": {
      "get": {
        "operationId": "getHanziStrokeData",
        "summary": "Get Hanzi Writer compatible stroke path data",
        "parameters": [
          {
            "name": "char",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1
            },
            "description": "One Chinese character, for example 学."
          }
        ],
        "responses": {
          "200": {
            "description": "Hanzi Writer compatible stroke data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StrokeDataResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "ApiError": {
        "description": "API error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "schemas": {
      "HanziWriting": {
        "type": "object",
        "required": ["char", "type", "pinyins", "radical", "strokeNames", "words", "howToWrite", "writingAdvice"],
        "properties": {
          "char": {
            "type": "string",
            "examples": ["学"]
          },
          "type": {
            "type": "string",
            "const": "hanzi"
          },
          "pinyin": {
            "type": "string",
            "examples": ["xué"]
          },
          "pinyins": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [["jué", "jiào"]]
          },
          "radical": {
            "type": "string",
            "examples": ["子"]
          },
          "strokeCount": {
            "type": ["integer", "null"],
            "examples": [8]
          },
          "strokeNames": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "meaning": {
            "type": "string"
          },
          "words": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "howToWrite": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StrokeInstruction"
            }
          },
          "writingAdvice": {
            "type": "string"
          },
          "source": {
            "type": "object"
          },
          "links": {
            "type": "object"
          }
        }
      },
      "PhraseWriting": {
        "type": "object",
        "required": ["text", "type", "length", "characters", "writingAdvice"],
        "properties": {
          "text": {
            "type": "string",
            "examples": ["学习"]
          },
          "type": {
            "type": "string",
            "const": "phrase"
          },
          "length": {
            "type": "integer"
          },
          "characters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HanziWriting"
            }
          },
          "writingAdvice": {
            "type": "string"
          },
          "links": {
            "type": "object"
          }
        }
      },
      "StrokeInstruction": {
        "type": "object",
        "required": ["index", "name", "instruction"],
        "properties": {
          "index": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "instruction": {
            "type": "string"
          }
        }
      },
      "StrokeDataResponse": {
        "type": "object",
        "required": ["char", "type", "source", "data"],
        "properties": {
          "char": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "const": "hanzi-writer-data"
          },
          "source": {
            "type": "string",
            "format": "uri"
          },
          "data": {
            "type": "object"
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}