[Backend API] Review current OpenAPI doc for linting

[justinyoo]

OpenAPI doc for the Backend API needs to be analysed

[justinyoo]

• OpenAPI 3.0.1 spec: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md
• Swashbuckle: https://github.com/domaindrivendev/Swashbuckle.AspNetCore

[justinyoo]

• https://marketplace.visualstudio.com/items?itemName=stoplight.spectral
• https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview

[tae0y]

asis 분석

• swagger 설정 : src/AzureOpenAIProxy.ApiApp/Extensions/ServiceCollectionExtensions.cs > AddOpenApiService 부분에서 OpenAPI 설정을 함
• 각 엔드포인트별 OpenAPI 설정 : src/AzureOpenAIProxy.ApiApp/Endpoints/WeatherForecastEndpoint.cs와 같이 엔드포인트별로 요청/응답을 어노테이션, 메서드 체인 등으로 설정함
  • src/AzureOpenAIProxy.ApiApp/Program.cs 설정한 엔드포인트를 app.AddWeatherForecast(); 구문과 같이 추가해줌

openapi 린팅 방법

1. vscode/visual studio : spectral를 설치
2. 앱을 구동한 뒤 swagger.json을 로컬에 다운받기
3. 다운받은 swagger.json에서 린트되는 항목을 수정

openapi 적용방법

• src/AzureOpenAIProxy.ApiApp/Endpoints/ChatCompletionsEndpoint.cs의 경우를 참조

// 요청 페이로드 정의
.Accepts<ChatCompletionOptions>(contentType: "application/json")
// 응답 페이로드 정의
.Produces<ChatCompletion>(statusCode: StatusCodes.Status200OK, contentType: "application/json")
.Produces(statusCode: StatusCodes.Status401Unauthorized)
.Produces<string>(statusCode: StatusCodes.Status500InternalServerError, contentType: "text/plain")
// 태그, 이름, 요약, 설명 등 기타항목 추가
.WithTags("openai")
.WithName("GetChatCompletions")
.WithOpenApi(operation =>
{
    operation.Summary = "Get chat completions";
    operation.Description = "Gets the chat completions";
    return operation;
});

• 만약 빠뜨렸을 경우에는?
  1. 아래와 같이 태그 명명규칙을 빼먹으면
  2. 다운받은 swagger.json에 warning이 뜨고
  3. vscode의 경우 출력탭에서 spectral로 뷰를 설정하면
  4. warning 내용이 자세히 나온다

[tae0y]

• spectral 설정하면 openapi v2,3이 기본 적용됨
  • 정확히 openapi 3.0.1을 적용하는 방법은 조사필요
• 현재 백엔드 엔드포인트는 OpenAPI 항목중에서 요청/응답 페이로드, 태그/이름/요약/설명을 정의중
  • 추가해야할 필수값이 있을지 팀에서 의논 필요

[justinyoo]

@tae0y 스펙트럴에 built-in OpenAPI 룰셋이 있습니다. 그걸 적용하시면 됩니다: https://docs.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules

아마도 어쩌면 커스텀 룰셋이 필요할 수도 있는데, 그 때는 요런 식으로 우리만의 룰셋 파일을 하나 만들어 보는 것도 나쁘지 않습니다: https://github.com/Azure-Samples/APICenter-Reference/blob/main/resources/rulesets/oas.yaml

만약 현재 자동으로 생성되는 OpenAPI 문서를 위의 built-in OpenAPI 룰셋으로 돌렸을 때 문제가 없다고 판단한다면, 커스텀 룰셋 하나만 만들어 보세요.