OpenAPI file structure for Stoplight documentation

Đang mở
  • Có gì không ổn?
#5 4 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
openapi, yaml
Lĩnh vực
api, documentation

Hướng nghiên cứu

Issue không nêu tên tệp hoặc kiểm thử nào. Hãy bắt đầu bằng việc xem xét bố cục YAML hiện tại của Stoplight/OpenAPI và các định nghĩa API của CDS Events, Curb và Metrics; được xem là hoàn tất khi mỗi API có tệp YAML riêng và mọi mô hình dùng chung đều được tham chiếu nhất quán.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

documentation
Is your feature request related to a problem? Please describe.

When we are building out the OpenAPI files within Stoplight, I believe we need to align on how we should structure the YAML files.

  • Option A: 1 YAML file for all of the CDS APIs
  • Option B: 1 YAML file for each of the CDS APIs
Describe the solution you'd like

I would like to pursue Option B which is the creation of a YAML file for each of the CDS APIs (Events, Curb, Metrics). This could make the documentation modular and easier to digest when being displayed through Stoplight.

Is this a breaking change

This isn't a breaking change since we have yet to finalize a full Open API version on our documentation

Impacted Spec

All APIs are impacted with this documentation standard.

Describe alternatives you've considered

We would want to use Stoplight to create shared models that can be referenced by multiple APIs if these are needed. This proposed structure does not conflict with previous decisions to maintain a single branch for each API version.

Additional context

Several members of the CDS WGSC collectively showed support for the option to move towards a model where 3 distinct files were used to document each API in the Oct 11th WGSC meeting.

Ngôn ngữ chính
JavaScript
Star
7
Fork
0
Không có pull request nào được merge trong 30 ngày

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của openmobilityfoundation/cds-openapi

Tất cả issue của openmobilityfoundation/cds-openapi

Issue tương tự

Thêm issue về JavaScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.