引言#
在任何应用程序开发过程中，实现后端和前端开发人员之间的无缝协调至关重要。这不仅确保了项目的高效交付，还最大限度地减少了误解，缩短了开发时间，并提高了产品质量。提出的开发计划流程解决了这两个关键角色之间更好同步的需求。
背景和动机#
Retrospec反馈突显了API可见性和计划方面的重大差距。随着技术的快速进步，对动态和适应性系统的需求不断增加。所提出的方法将在计划阶段纳入后端和前端工程师，旨在从一开始就确保清晰度和一致性。
提议的流程#
1. 选择代表:#
每周将选择一名后端和一名前端工程师。这些代表将负责理解冲刺的要求并将其与当前的计划OpenAPI架构对齐。
2. 审查和修订:#
被选中的工程师将协作审查OpenAPI配置。他们将确保它与要求一致，并在必要时进行修订。这种协作确保双方对需要实现的目标有清晰的理解。
3. 提交和生成:#
修订后，对OpenAPI配置的更改将提交到相应的存储库。随后，CI/CD将使用提供的yaml生成模拟API。
4. 冲刺完成:#
冲刺完成后，将生成新的yaml。这个yaml将封装下一个冲刺的API要求。
工具和管理:#
YAML可视化: 可以利用Swagger Editor中的在线工具上传yaml并将其可视化为Swagger文档。
OpenAPI文档管理: 重要的是要理解这个提议的流程纯粹是为了计划阶段。一旦API被部署，相应的服务应该生成其openapi.json。然后可以下载此JSON并重新用于进一步的计划。
CI/CD角色: CI/CD管道将发挥关键作用。它应该被设计为接受yaml文件并根据规范部署模拟服务器。可以考虑使用openapi-mock这样的工具来实现这一目的。
为什么这个流程有益:#
增强沟通: 通过在计划过程中包括后端和前端工程师，建立了直接的沟通线路。这最大限度地减少了误解和模糊性，从而实现更精简的开发过程。
改进的一致性: 两个团队都可以对API要求和功能有清晰的理解和协议。这意味着开发阶段的来回更少。
效率: 根据规范部署模拟服务器后，开发人员可以无延迟地开始工作，从而更快地发布产品。
质量保证: 当后端和前端开发人员从一开始就参与时，忽视关键要求的可能性就会减少。这会产生更强大、功能更好的最终产品。
结论#
提出的开发计划流程强调后端和前端工程师之间的协作。通过使用Swagger进行可视化和openapi-mock进行模拟服务器部署等工具，该流程不仅弥合了沟通差距，还确保开发的API完全符合要求。随着技术的不断发展，正是这样的流程将确保团队能够跟上需求，同时保持产品质量。
附录A - yaml示例#
openapi: 3.1.0
info:
title: PKY Sprint 3
description: |-
PKY Sprint 3 Development Schema
termsOfService:
contact:
email: jared@lynskey.co.nz
license:
name: None
url:
version: 1.0.11
externalDocs:
description:
url:
servers:
- url: https://api-mock.com/api/v3
tags:
- name: curation
description: PKY-1081 Curated Lists Feature
externalDocs:
description: Jira Epic
url: https://pickydev.atlassian.net/browse/PKY-1081
paths:
/curations:
get:
tags:
- curation
summary: Return the curations created by users
description: Returns a map of status codes to quantities
operationId: getCurations
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
additionalProperties:
type: integer
format: int32
security:
- api_key: []
/curations/{curationId}:
get:
tags:
- curation
summary: Find purchase order by ID
description: For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions.
operationId: getOrderById
parameters:
- name: orderId
in: path
description: ID of order that needs to be fetched
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
application/xml:
schema:
$ref: '#/components/schemas/Order'
'400':
description: Invalid ID supplied
'404':
description: Order not found
delete:
tags:
- curation
summary: Delete purchase order by ID
description: For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
operationId: deleteOrder
parameters:
- name: orderId
in: path
description: ID of the order that needs to be deleted
required: true
schema:
type: integer
format: int64
responses:
'400':
description: Invalid ID supplied
'404':
description: Order not found
components:
schemas:
Curation:
type: object
properties:
id:
type: integer
format: int64
examples: [10]
curationId:
type: integer
format: int64
examples: [198772]
quantity:
type: integer
format: int32
examples: [7]
status:
type: string
description: Order Status
examples: [approved]
enum:
- placed
- approved
- delivered
complete:
type: boolean
xml:
name: order
ApiResponse:
type: object
properties:
code:
type: integer
format: int32
type:
type: string
message:
type: string
xml:
name: '##default'
requestBodies:
Curation:
description: Curation object that needs to be added
content:
application/json:
schema:
$ref:
application/xml:
schema:
$ref:
securitySchemes:
petstore_auth:
type: oauth2
flows:
implicit:
authorizationUrl:
scopes:
write:curations: modify curations in your account
read:curations: read your curations
api_key:
type: apiKey
name: api_key
in: header