Add spectral rules #20

[tae0y]

related to #20, #21, #221
필수 필드를 지정하고, 해당 필드가 없을 경우 에러를 발생시키도록 수정

spectral openapi 기본 룰셋을 확장해서
현재 기준으로 weatherforecast, chat/completions에 지정된 필드들을 필수값으로 지정해서
없을 경우에는 error를 발생시키도록 해보았습니다~
(세부내용은 .spectral.yaml 각주에 기재해두었습니다!)

ruleset 테스트코드

# .NET 프로젝트를 백그라운드에서 실행
dotnet run --project src/AzureOpenAIProxy.AppHost &

# .NET 프로젝트의 PID를 저장
DOTNET_PID=$!

# .NET 프로젝트가 완전히 기동될 때까지 대기 (필요에 따라 조정)
sleep 10

# Swagger 파일 다운로드
rm -f swagger.json
curl https://localhost:7001/swagger/v1.0.0/swagger.json -O

# .NET 프로젝트 종료
kill $DOTNET_PID

# Spectral로 린트 수행
spectral lint swagger.json

ruleset 테스트방법

• API 버전 규칙 : v로 시작하고 숫자와 점으로 이루어져야 함

//----------------------------------------------------------------------
// src/AzureOpenAIProxy.ApiApp/Extensions/ServiceCollectionExtensions.cs
//----------------------------------------------------------------------
// 수정전
var info = new OpenApiInfo()
{
    Version = Constants.Version, //"v1.0.0"

//----------------------------------------------------------------------
// 수정후 error
var info = new OpenApiInfo()
{
    Version = "1.0.0",

• 모든 엔드포인트는 tags를 포함해야 함

//----------------------------------------------------------------------
// src/AzureOpenAIProxy.ApiApp/Endpoints/WeatherForecastEndpoint.cs
//----------------------------------------------------------------------
// 수정전
var builder = app.MapGet(EndpointUrls.WeatherForecast, () => {
            //( 생략 ... )
        })
        .WithTags("weather")

//----------------------------------------------------------------------
// 수정후 warn - tags는 암시적으로 생성됨, 
var builder = app.MapGet(EndpointUrls.WeatherForecast, () => {
            //( 생략 ... )
        })
        //.WithTags("weather")

//----------------------------------------------------------------------
// error - swagger.json를 직접 수정하면 발생

• 모든 엔드포인트는 operationId를 포함해야 함 (.WithName 으로 지정)

//----------------------------------------------------------------------
// src/AzureOpenAIProxy.ApiApp/Endpoints/WeatherForecastEndpoint.cs
//----------------------------------------------------------------------
// 수정전
var builder = app.MapGet(EndpointUrls.WeatherForecast, () => {
            //( 생략 ... )
        })
        .WithName("GetWeatherForecast")

//----------------------------------------------------------------------
// 수정후 error
var builder = app.MapGet(EndpointUrls.WeatherForecast, () => {
            //( 생략 ... )
        })
        //.WithName("GetWeatherForecast")

• 모든 엔드포인트는 summary와 description을 포함해야 함

//----------------------------------------------------------------------
// src/AzureOpenAIProxy.ApiApp/Endpoints/WeatherForecastEndpoint.cs
//----------------------------------------------------------------------
// 수정전
var builder = app.MapGet(EndpointUrls.WeatherForecast, () =>
            //( 생략 ... )
        })
        .WithOpenApi(operation =>
        {
            operation.Summary = "Get weather forecast";
            operation.Description = "Gets the weather forecast";

            return operation;
        });

//----------------------------------------------------------------------
// 수정후 error
var builder = app.MapGet(EndpointUrls.WeatherForecast, () =>
            //( 생략 ... )
        })
        .WithOpenApi(operation =>
        {
            //operation.Summary = "Get weather forecast";
            //operation.Description = "Gets the weather forecast";

            return operation;
        });

• 응답이 정의되어 있어야함

//----------------------------------------------------------------------
// src/AzureOpenAIProxy.ApiApp/Endpoints/WeatherForecastEndpoint.cs
//----------------------------------------------------------------------
// 수정전
var builder = app.MapGet(EndpointUrls.WeatherForecast, () =>
            //( 생략 ... )
        })
        .Produces<WeatherForecast>(statusCode: StatusCodes.Status200OK, contentType: "application/json")
        .Produces(statusCode: StatusCodes.Status401Unauthorized)
        .Produces<string>(statusCode: StatusCodes.Status500InternalServerError, contentType: "text/plain")

//----------------------------------------------------------------------
// 수정후 - response를 아무것도 정의하지 않으면 200 OK가 암시적으로 생성. error를 발생시키지 않음.
var builder = app.MapGet(EndpointUrls.WeatherForecast, () =>
            //( 생략 ... )
        })
        //.Produces<WeatherForecast>(statusCode: StatusCodes.Status200OK, contentType: "application/json")
        //.Produces(statusCode: StatusCodes.Status401Unauthorized)
        //.Produces<string>(statusCode: StatusCodes.Status500InternalServerError, contentType: "text/plain")

• 응답 코드 규칙 : 200, 401, 500 응답 코드가 모두 있어야 함

//----------------------------------------------------------------------
// src/AzureOpenAIProxy.ApiApp/Endpoints/WeatherForecastEndpoint.cs
//----------------------------------------------------------------------
// 수정전
var builder = app.MapGet(EndpointUrls.WeatherForecast, () =>
            //( 생략 ... )
        })
        .Produces<WeatherForecast>(statusCode: StatusCodes.Status200OK, contentType: "application/json")
        .Produces(statusCode: StatusCodes.Status401Unauthorized)
        .Produces<string>(statusCode: StatusCodes.Status500InternalServerError, contentType: "text/plain")

//----------------------------------------------------------------------
// 수정후 error
var builder = app.MapGet(EndpointUrls.WeatherForecast, () =>
            //( 생략 ... )
        })
        .Produces<WeatherForecast>(statusCode: StatusCodes.Status200OK, contentType: "application/json")
        //.Produces(statusCode: StatusCodes.Status401Unauthorized)
        //.Produces<string>(statusCode: StatusCodes.Status500InternalServerError, contentType: "text/plain")

• 401을 제외한 모든 응답 코드는 content를 포함해야함

//----------------------------------------------------------------------
// src/AzureOpenAIProxy.ApiApp/Endpoints/WeatherForecastEndpoint.cs
//----------------------------------------------------------------------
// 수정전
var builder = app.MapGet(EndpointUrls.WeatherForecast, () =>
            //( 생략 ... )
        })
        .Produces<WeatherForecast>(statusCode: StatusCodes.Status200OK, contentType: "application/json")
        .Produces(statusCode: StatusCodes.Status401Unauthorized)
        .Produces<string>(statusCode: StatusCodes.Status500InternalServerError, contentType: "text/plain")

//----------------------------------------------------------------------
// 수정후 error
var builder = app.MapGet(EndpointUrls.WeatherForecast, () =>
            //( 생략 ... )
        })
        //.Produces<WeatherForecast>(statusCode: StatusCodes.Status200OK, contentType: "application/json")
        .Produces(statusCode: StatusCodes.Status401Unauthorized) // content가 없는데 오류가 나지 않음
        .Produces(statusCode: StatusCodes.Status500InternalServerError) // content가 없어서 오류가 발생함

[justinyoo]

좋습니다! 이 커스텀 룰셋을 로컬에서 테스트해 보려면 각 규칙별로 어떻게 해야 하는지를 PR 본문에 적어주시면 좋겠습니다.

[justinyoo]

몇가지 불필요한 규칙만 삭제하면 될 듯 싶습니다.

[github-actions]

Test Results

✔️ Tests 35 / 35 - passed in 17.5s
🔍 click here for more details

✏️ updated for commit f9791d4

[github-actions]

Test Results

Tests

📋 Total	✔️ Passed	❌ Failed	⚠️ Skipped
35	35	0	0

[justinyoo]

LGTM @tae0y 수고하셨습니다!