{
  "openapi": "3.0.3",
  "info": {
    "title": "SteelWe（钢维）Open API",
    "version": "1.0.0",
    "description": "公开读取接口无需认证；写入接口需 Authorization: Bearer <JWT>（由 /api/v1/auth/login 或魔法链接获取）。",
    "contact": {
      "name": "SteelWe",
      "url": "https://steelwe.com/zh/developers"
    }
  },
  "servers": [
    {
      "url": "https://steelwe.com"
    }
  ],
  "tags": [
    {
      "name": "knowledge",
      "description": "知识库"
    },
    {
      "name": "community",
      "description": "问答"
    },
    {
      "name": "forum",
      "description": "社区"
    },
    {
      "name": "standards",
      "description": "标准对照"
    },
    {
      "name": "profiles",
      "description": "企业/专家"
    },
    {
      "name": "auth",
      "description": "认证"
    }
  ],
  "paths": {
    "/api/v1/questions": {
      "get": {
        "tags": [
          "community"
        ],
        "summary": "问答列表",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "locale",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "zh",
                "en"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "问答分页",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/knowledge": {
      "get": {
        "tags": [
          "knowledge"
        ],
        "summary": "知识库列表",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "知识库分页",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/knowledge/{slug}": {
      "get": {
        "tags": [
          "knowledge"
        ],
        "summary": "知识详情（含正文）",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "知识详情",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/standards": {
      "get": {
        "tags": [
          "standards"
        ],
        "summary": "牌号标准对照查询",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "example": "316L"
          }
        ],
        "responses": {
          "200": {
            "description": "标准映射列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/defects": {
      "get": {
        "tags": [
          "knowledge"
        ],
        "summary": "加工缺陷图谱",
        "responses": {
          "200": {
            "description": "缺陷列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/orgs": {
      "get": {
        "tags": [
          "profiles"
        ],
        "summary": "企业能力档案",
        "responses": {
          "200": {
            "description": "企业分页",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/experts": {
      "get": {
        "tags": [
          "profiles"
        ],
        "summary": "认证专家",
        "responses": {
          "200": {
            "description": "专家分页",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/boards": {
      "get": {
        "tags": [
          "forum"
        ],
        "summary": "社区圈子列表",
        "responses": {
          "200": {
            "description": "圈子列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/posts": {
      "get": {
        "tags": [
          "forum"
        ],
        "summary": "社区帖子列表",
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "latest",
                "hot"
              ],
              "default": "latest"
            }
          },
          {
            "name": "board",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "帖子分页",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/posts/{id}": {
      "get": {
        "tags": [
          "forum"
        ],
        "summary": "帖子详情（含评论）",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "帖子详情",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/providers": {
      "get": {
        "tags": [
          "auth"
        ],
        "summary": "可用的第三方登录方式",
        "responses": {
          "200": {
            "description": "providers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/login": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "邮箱密码登录，返回 JWT",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 8
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "accessToken / refreshToken / user",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/actuator/health": {
      "get": {
        "tags": [
          "auth"
        ],
        "summary": "服务健康检查",
        "responses": {
          "200": {
            "description": "status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}