[TIL] swagger

Swagger이란?

• Open Api Specification(OAS)를 위한 프레임워크이다.

그렇다면 OAS란 무엇인가?
간단하게 정리하자면,

• OpenApi = Specification
• Swagger = Tools for implementing the specification

OAS(OpenAPI Specification)는 REST APIs 웹서비스를 약속된 규칙에 따라 약속된 규칙에 맞게 API spec들을 JSON이나 YAML 형식으로 표현할 수 있다. 이를 통해, 직접 소스코드를 보거나 추가 문서 필요없이 서비스를 이해할 수 있다. 그렇다면 json과 YAML 형식의 차이점은 무엇일까? 궁금했다.

The difference btw JSON and YAML

결론부터 말하자면
stack overflow의 도움을 받아본 결과, 엄청나게 큰 차이는 없었다.
(In terms of features, there is no difference btw using JSON or YAML.)

// JSON

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

// YAML 

servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server

• since YAML is a superset of JSON, both are valid JSON and valid YAML.
• The second one is valid YAML and structually identical to the first document.
  => There is no difference btw them.