microsoft / microsoft/typespec

OAS3 emitter should have the capability to generate the specification into multiple files

Open
#5,464 0 comments 1 reaction 1 assignee Claimed by @wanlwanl View on GitHub
design:needed emitter:openapi3 triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### Clear and concise description of the problem

For smaller APIs, it is better to keep everything in a single file for simplicity.
However, as the API grows, it becomes more practical to put the specification into multiple files. This would helps in managing and maintaining the spec more efficiently.

Today, OAS3 emitter only provides limited functions for the output file and it does not support generate the specification into multiple files. https://typespec.io/docs/emitters/openapi3/reference/emitter/

Proposal:
To have one more emitter config to control the generation. so that we could have

- models: Put all model definitions in a separate file.
- Paths: Defining each endpoint's operations in separate files .
- Parameters and Responses: Storing reusable parameters and responses in their own files.

We could also consider leverage namespace defined in tsp to further split the huge file.

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Read the [docs](https://typespec.io/docs/).
- [x] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.