이번 세션은 문서화보다는 OpenAPI 스펙 관점에서 설명하는 내용이라 살짝 애매합니다. AI 보다는 코드 생성이 중요한 곳에서 OpenAPI 스펙을 어떻게 만들어야 하는지 설명하는 내용이라고 볼 수 있네요.
- We don't have an OpenAPI spec
The Problem: "We've put off creating a spec. We want to make one, but we aren't sure if we should generate it or hand-maintain it."
The Solution: Pick one, or try both and see what sticks. Every org is different.
OpenAPI 스펙을 유지하는 방법이 정해진 정답이 있는 것은 아니라는 것입니다. 고민되는 지점의 방식을 모두 실행해 보고 조직의 성격에 맞는 것을 골라야 합니다.
- "Governance is a pre-req Code Gen"
The Problem: "Before we use our spec for code gen, we need proper staffing to build a governance workflow... People aren't invested in governance because there's no critical workflows using the spec."
The Solution: "Overcome the chicken & egg. Start small and do code gen for a couple endpoints. Create incentive for the eng team."
역시 선택의 문제인데, 작은 규모로 시작해보고 개발팀에서 어떤 혜택을 볼 수 있는지 경험할 수 있게 하는 것이 중요합니다.
- Pay attention to operationlds
If you're generating your spec from code, pay special attention to this.
Use in Code gen: operationlds are typically used to name method calls
Some good rules to follow:
* Make them descriptive & human readable.
* Follow a consistent pattern.
* Stick to alphanumerics & simple separators i.e. - or_
verb_object i.e. list_drinks
operationId을 작성할 때는 일관되고 이해할 수 있는 명명 규칙을 사용해야 합니다.
참고: https://redocly.com/blog/operationid-is-api-design
- Reuse component schemas when possible
Generating a spec from code will often use inline schemas by default. They usually provide a way for for you to make something as a shared type
Use in Code gen: component schemas will become shared types.
Why you should use component schema:
* Easier maintenance
* Improved readability
컴포넌트 스키마를 사용해야 하는 이유는 유지관리를 쉽게 하고 가독성을 좋게 한다는 장점만 이야기하고 있지만, 재사용 구성을 잘못하면 오히려 스펙을 이해하기 어렵고 변경에 따른 비용이 증가할 수 있고 복잡해지는 문제도 있습니다.
- Use tags to group your resources
Use in Code gen: tags are used to group methods into namespaces.
Tips for effective use:
* Use them.
* Have a tag for each resource your API exposes.
* Think carefully before you associate a method to multiple tags.
* Make sure it doesn't conflict with your docsite
문서 사이트와 충돌한다는 것은 태그를 사용해서 자동으로 스펙 문서가 생성되는데 적절한 태그를 설정하지 않으면 문서 사이트의 구조와 어긋나는 경우가 있을 수 있고 중복된 문서가 생성되는 등의 문제가 있을 수 있다고 하네요.
- Don't shy away from failure, include error codes
Use in Code gen: error codes & associated response objects become error classes.
Tips for effective use:
* Use them.
* Define component schemas for the error responses.
* The more you enumerate, the better.
사용자들이 오류 응답을 만날 때 이를 적절하게 활용할 수 있게 해야 합니다. 사용자들은 성공보다 실패를 더 많이 경험할 수 있습니다.
- Avoid anyOf, use oneOf
Use in Code gen: any Of doesn't really make sense in the context of codegen, so I'd advise not to use it.
Tips for effective use:
* For union types, use oneOf
코드 생성 관점에서는 그렇다는 겁니다. 상황에 따라 다를 수 있겠죠.
Nolan Di Mare Sullivan: Get Your OpenAPI Spec Ready For Code Generation
https://youtu.be/dGIwQ_JPQaQ?si=q26rmI34919THu3L
