alps2openapi

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ALPS to OpenAPI Converter

ALPS 转 OpenAPI 转换器

Generate OpenAPI 3.1 specification from ALPS profile with validation loop.

从ALPS配置文件生成带有验证循环的OpenAPI 3.1规范。

When to Use

适用场景

User asks to generate OpenAPI from ALPS
User wants to create REST API documentation from ALPS profile
User says "alps2openapi", "convert to openapi", "generate api spec"

用户要求从ALPS生成OpenAPI
用户希望从ALPS配置文件创建REST API文档
用户提及"alps2openapi"、"convert to openapi"、"generate api spec"

Conversion Rules

转换规则

1. Transition Type → HTTP Method

1. 转换类型 → HTTP 方法

ALPS type	HTTP Method	Description
safe	GET	Read operations
unsafe	POST	Create operations (non-idempotent)
idempotent	PUT/DELETE/PATCH	Update/Delete operations (idempotent)

ALPS 类型	HTTP 方法	描述
safe	GET	读取操作
unsafe	POST	创建操作（非幂等）
idempotent	PUT/DELETE/PATCH	更新/删除操作（幂等）

Determining idempotent Method

幂等方法判断

Infer from transition ID:

PUT (Update):

Keywords:
```
update
```
,
```
edit
```
,
```
modify
```
,
```
change
```
,
```
set
```
,
```
replace
```
Example:
```
doUpdateUser
```
,
```
doEditPost
```
,
```
doSetStatus
```

DELETE:

Keywords:
```
delete
```
,
```
remove
```
,
```
cancel
```
,
```
clear
```
,
```
destroy
```
Example:
```
doDeleteUser
```
,
```
doRemoveItem
```
,
```
doCancelOrder
```

PATCH:

Keywords:
```
toggle
```
,
```
patch
```
,
```
increment
```
,
```
decrement
```
Example:
```
doToggleComplete
```
,
```
doPatchProfile
```

从转换ID推断：

PUT（更新）：

关键词：
```
update
```
、
```
edit
```
、
```
modify
```
、
```
change
```
、
```
set
```
、
```
replace
```
示例：
```
doUpdateUser
```
、
```
doEditPost
```
、
```
doSetStatus
```

DELETE：

关键词：
```
delete
```
、
```
remove
```
、
```
cancel
```
、
```
clear
```
、
```
destroy
```
示例：
```
doDeleteUser
```
、
```
doRemoveItem
```
、
```
doCancelOrder
```

PATCH：

关键词：
```
toggle
```
、
```
patch
```
、
```
increment
```
、
```
decrement
```
示例：
```
doToggleComplete
```
、
```
doPatchProfile
```

2. Transition ID → operationId

2. 转换ID → operationId

Use ALPS transition ID directly as operationId:

```
goTodoList
```
→
```
operationId: goTodoList
```
```
doCreateTodo
```
→
```
operationId: doCreateTodo
```

直接使用ALPS转换ID作为operationId：

```
goTodoList
```
→
```
operationId: goTodoList
```
```
doCreateTodo
```
→
```
operationId: doCreateTodo
```

3. Path Generation

3. 路径生成

Transition Pattern	Path	Method
goXxxList	/xxxs	GET
goXxxDetail	/xxxs/{xxxId}	GET
doCreateXxx	/xxxs	POST
doUpdateXxx	/xxxs/{xxxId}	PUT
doDeleteXxx	/xxxs/{xxxId}	DELETE
doToggleYyy	/xxxs/{xxxId}/yyy	PATCH

转换模式	路径	方法
goXxxList	/xxxs	GET
goXxxDetail	/xxxs/{xxxId}	GET
doCreateXxx	/xxxs	POST
doUpdateXxx	/xxxs/{xxxId}	PUT
doDeleteXxx	/xxxs/{xxxId}	DELETE
doToggleYyy	/xxxs/{xxxId}/yyy	PATCH

Path Naming Rules

路径命名规则

Use lowercase plural nouns:
```
/todos
```
,
```
/users
```
,
```
/products
```
Use kebab-case for multi-word:
```
/order-items
```
,
```
/user-profiles
```
Nested resources:
```
/users/{userId}/posts
```

使用小写复数名词：
```
/todos
```
、
```
/users
```
、
```
/products
```
多词使用短横线分隔：
```
/order-items
```
、
```
/user-profiles
```
嵌套资源：
```
/users/{userId}/posts
```

4. Schema Generation

4. Schema 生成

Semantic Fields → Properties

语义字段 → 属性

Map ALPS semantic descriptors to OpenAPI schema properties:

yaml

undefined

将ALPS语义描述符映射到OpenAPI schema属性：

yaml

undefined

ALPS

{"id": "todoId", "title": "Task ID", "def": "https://schema.org/identifier"}

{"id": "todoId", "title": "任务ID", "def": "https://schema.org/identifier"}

OpenAPI

todoId: type: string description: Task ID

undefined

todoId: type: string description: 任务ID

undefined

States → Schema Names

状态 → Schema 名称

ALPS states become OpenAPI schema names:

```
TodoList
```
→
```
TodoListItem
```
(for list responses)
```
TodoDetail
```
→
```
TodoDetail
```
(for single item responses)

ALPS状态成为OpenAPI schema名称：

```
TodoList
```
→
```
TodoListItem
```
（列表响应）
```
TodoDetail
```
→
```
TodoDetail
```
（单条数据响应）

5. schema.org → OpenAPI Format Mapping

5. schema.org → OpenAPI 格式映射

schema.org	OpenAPI
https://schema.org/DateTime	`type: string, format: date-time`
https://schema.org/Date	`type: string, format: date`
https://schema.org/Time	`type: string, format: time`
https://schema.org/Email	`type: string, format: email`
https://schema.org/URL	`type: string, format: uri`
https://schema.org/identifier	`type: string`
https://schema.org/Integer	`type: integer`
https://schema.org/Number	`type: number`
https://schema.org/Boolean	`type: boolean`
https://schema.org/Text	`type: string`

schema.org	OpenAPI
https://schema.org/DateTime	`type: string, format: date-time`
https://schema.org/Date	`type: string, format: date`
https://schema.org/Time	`type: string, format: time`
https://schema.org/Email	`type: string, format: email`
https://schema.org/URL	`type: string, format: uri`
https://schema.org/identifier	`type: string`
https://schema.org/Integer	`type: integer`
https://schema.org/Number	`type: number`
https://schema.org/Boolean	`type: boolean`
https://schema.org/Text	`type: string`

6. Input Parameters

6. 输入参数

Extract from transition's nested descriptors:

json

{"id": "doCreateTodo", "type": "unsafe", "rt": "#TodoDetail", "descriptor": [
  {"href": "#title"},
  {"href": "#description"},
  {"href": "#dueDate"}
]}

Becomes:

yaml

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CreateTodoRequest'

With schema:

yaml

CreateTodoRequest:
  type: object
  properties:
    title:
      type: string
    description:
      type: string
    dueDate:
      type: string
      format: date-time
  required:
    - title

从转换的嵌套描述符中提取：

json

{"id": "doCreateTodo", "type": "unsafe", "rt": "#TodoDetail", "descriptor": [
  {"href": "#title"},
  {"href": "#description"},
  {"href": "#dueDate"}
]}

转换后：

yaml

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CreateTodoRequest'

对应的schema：

yaml

CreateTodoRequest:
  type: object
  properties:
    title:
      type: string
    description:
      type: string
    dueDate:
      type: string
      format: date-time
  required:
    - title

7. HTTP Status Codes

7. HTTP 状态码

Operation	Success	Client Error	Not Found
GET (single)	200	400	404
GET (list)	200	400	-
POST	201	400, 409	-
PUT	200	400	404
PATCH	200	400	404
DELETE	204	400	404

操作	成功状态	客户端错误	未找到
GET（单条）	200	400	404
GET（列表）	200	400	-
POST	201	400, 409	-
PUT	200	400	404
PATCH	200	400	404
DELETE	204	400	404

8. Error Response Schema

8. 错误响应 Schema

Always include standard error schema:

yaml

components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
      required:
        - code
        - message

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

始终包含标准错误schema：

yaml

components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: 错误码
        message:
          type: string
          description: 错误信息
      required:
        - code
        - message

  responses:
    NotFound:
      description: 资源未找到
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: 请求无效
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

9. Required Fields

9. 必填字段

Request (POST/PUT):

Fields in transition's descriptor are required by default
Mark as optional with
```
(optional)
```
in ALPS doc

Response:

ID field is always required
Primary fields (title, name, etc.) are required
Timestamps (createdAt, updatedAt) are required

请求（POST/PUT）：

转换描述符中的字段默认必填
在ALPS文档中标记
```
(optional)
```
则为可选

响应：

ID字段始终必填
主要字段（标题、名称等）必填
时间戳（createdAt、updatedAt）必填

10. Tags from ALPS

10. 从ALPS提取标签

Use ALPS

tag

attribute for OpenAPI tags:

json

{"id": "goTodoList", "type": "safe", "rt": "#TodoList", "tag": "todo"}

Becomes:

yaml

tags:
  - todo

使用ALPS的

tag

属性作为OpenAPI标签：

json

{"id": "goTodoList", "type": "safe", "rt": "#TodoList", "tag": "todo"}

转换后：

yaml

tags:
  - todo

Workflow

工作流程

Read ALPS profile - Parse JSON or XML
Extract components:
- Semantic fields → Schema properties
- States → Response schemas
- Transitions → Operations
Generate OpenAPI YAML

Validate with Spectral:

bash

npx @stoplight/spectral-cli lint <output_file>

Fix errors - If validation fails, fix and regenerate
Return result - Provide the validated OpenAPI spec

读取ALPS配置文件 - 解析JSON或XML
提取组件：
- 语义字段 → Schema属性
- 状态 → 响应schema
- 转换 → 操作
生成OpenAPI YAML

使用Spectral验证：

bash

npx @stoplight/spectral-cli lint <output_file>

修复错误 - 验证失败时，修复后重新生成
返回结果 - 提供经过验证的OpenAPI规范

Output Format

输出格式

YAML format (not JSON)
OpenAPI version: 3.1.0
Include
```
$schema
```
reference
Japanese descriptions from ALPS
```
title
```

YAML格式（非JSON）
OpenAPI版本：3.1.0
包含
```
$schema
```
引用
从ALPS的
```
title
```
生成日文描述（注：原文此处为日文，按要求保留逻辑，实际翻译时若为中文场景可调整，但此处按原文逻辑保留）

Template

模板

yaml

openapi: 3.1.0
info:
  title: {alps.title}
  description: {alps.doc}
  version: 1.0.0

servers:
  - url: http://localhost:8080/api
    description: Development server

paths:
  # Generated from transitions

components:
  schemas:
    # Generated from semantic descriptors and states
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

yaml

openapi: 3.1.0
info:
  title: {alps.title}
  description: {alps.doc}
  version: 1.0.0

servers:
  - url: http://localhost:8080/api
    description: 开发服务器

paths:
  # 从转换生成

components:
  schemas:
    # 从语义描述符和状态生成
    Error:
      type: object
      properties:
        code:
          type: string
          description: 错误码
        message:
          type: string
          description: 错误信息
      required:
        - code
        - message

  responses:
    NotFound:
      description: 资源未找到
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: 请求无效
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Validation

验证

After generating OpenAPI, validate:

bash

npx @stoplight/spectral-cli lint openapi.yaml

If errors occur:

Read error messages
Fix the issues in the generated spec
Re-validate until no errors

生成OpenAPI后，执行验证：

bash

npx @stoplight/spectral-cli lint openapi.yaml

若出现错误：

阅读错误信息
修复生成的规范中的问题
重新验证直到无错误

Example

示例

Input (ALPS)

输入（ALPS）

json

{
  "alps": {
    "title": "Todo API",
    "descriptor": [
      {"id": "todoId", "title": "Task ID"},
      {"id": "title", "title": "Title"},
      {"id": "completed", "title": "Completed"},

      {"id": "TodoList", "descriptor": [
        {"href": "#todoId"},
        {"href": "#title"},
        {"href": "#goTodoDetail"},
        {"href": "#doCreateTodo"}
      ]},

      {"id": "goTodoList", "type": "safe", "rt": "#TodoList"},
      {"id": "goTodoDetail", "type": "safe", "rt": "#TodoDetail", "descriptor": [
        {"href": "#todoId"}
      ]},
      {"id": "doCreateTodo", "type": "unsafe", "rt": "#TodoDetail", "descriptor": [
        {"href": "#title"}
      ]},
      {"id": "doDeleteTodo", "type": "idempotent", "rt": "#TodoList", "descriptor": [
        {"href": "#todoId"}
      ]}
    ]
  }
}

json

{
  "alps": {
    "title": "待办事项API",
    "descriptor": [
      {"id": "todoId", "title": "任务ID"},
      {"id": "title", "title": "标题"},
      {"id": "completed", "title": "已完成"},

      {"id": "TodoList", "descriptor": [
        {"href": "#todoId"},
        {"href": "#title"},
        {"href": "#goTodoDetail"},
        {"href": "#doCreateTodo"}
      ]},

      {"id": "goTodoList", "type": "safe", "rt": "#TodoList"},
      {"id": "goTodoDetail", "type": "safe", "rt": "#TodoDetail", "descriptor": [
        {"href": "#todoId"}
      ]},
      {"id": "doCreateTodo", "type": "unsafe", "rt": "#TodoDetail", "descriptor": [
        {"href": "#title"}
      ]},
      {"id": "doDeleteTodo", "type": "idempotent", "rt": "#TodoList", "descriptor": [
        {"href": "#todoId"}
      ]}
    ]
  }
}

Output (OpenAPI)

输出（OpenAPI）

yaml

openapi: 3.1.0
info:
  title: Todo API
  version: 1.0.0

paths:
  /todos:
    get:
      operationId: goTodoList
      summary: Get todo list
      responses:
        '200':
          description: Todo list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TodoListItem'

    post:
      operationId: doCreateTodo
      summary: Create todo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTodoRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TodoDetail'
        '400':
          $ref: '#/components/responses/BadRequest'

  /todos/{todoId}:
    parameters:
      - name: todoId
        in: path
        required: true
        schema:
          type: string

    get:
      operationId: goTodoDetail
      summary: Get todo detail
      responses:
        '200':
          description: Todo detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TodoDetail'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: doDeleteTodo
      summary: Delete todo
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    TodoListItem:
      type: object
      properties:
        todoId:
          type: string
          description: Task ID
        title:
          type: string
          description: Title
      required:
        - todoId
        - title

    TodoDetail:
      type: object
      properties:
        todoId:
          type: string
        title:
          type: string
        completed:
          type: boolean
      required:
        - todoId
        - title
        - completed

    CreateTodoRequest:
      type: object
      properties:
        title:
          type: string
      required:
        - title

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message

  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

yaml

openapi: 3.1.0
info:
  title: 待办事项API
  version: 1.0.0

paths:
  /todos:
    get:
      operationId: goTodoList
      summary: 获取待办事项列表
      responses:
        '200':
          description: 待办事项列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TodoListItem'

    post:
      operationId: doCreateTodo
      summary: 创建待办事项
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTodoRequest'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TodoDetail'
        '400':
          $ref: '#/components/responses/BadRequest'

  /todos/{todoId}:
    parameters:
      - name: todoId
        in: path
        required: true
        schema:
          type: string

    get:
      operationId: goTodoDetail
      summary: 获取待办事项详情
      responses:
        '200':
          description: 待办事项详情
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TodoDetail'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: doDeleteTodo
      summary: 删除待办事项
      responses:
        '204':
          description: 删除成功
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    TodoListItem:
      type: object
      properties:
        todoId:
          type: string
          description: 任务ID
        title:
          type: string
          description: 标题
      required:
        - todoId
        - title

    TodoDetail:
      type: object
      properties:
        todoId:
          type: string
          description: 任务ID
        title:
          type: string
          description: 标题
        completed:
          type: boolean
          description: 已完成
      required:
        - todoId
        - title
        - completed

    CreateTodoRequest:
      type: object
      properties:
        title:
          type: string
          description: 标题
      required:
        - title

    Error:
      type: object
      properties:
        code:
          type: string
          description: 错误码
        message:
          type: string
          description: 错误信息
      required:
        - code
        - message

  responses:
    NotFound:
      description: 资源未找到
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: 请求无效
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'