3장. API Cryostat를 사용하여 API 정의 설계 및 개발

절차

1. Fuse Online을 사용하는 경우 2 단계로 건너뜁니다.

   OpenShift에서 Fuse를 사용하는 경우:

   1. OpenShift 웹 콘솔에 로그인한 다음 API Creator가 포함된 프로젝트를 엽니다.

   2. OpenShift 4.x의 경우 Topology 를 선택한 다음 apicurito-service 아이콘에 대한 URL 링크를 클릭합니다.

      OpenShift 3.11의 경우 애플리케이션 목록에서 APIFilter의 URL을 클릭합니다(예: https://apidesigner-myproject.192.168.64.43.nip.io) .

      API의 새 브라우저 창 또는 탭이 열립니다.

      참고

      API Builder는 Apicurio Studio 오픈 소스 프로젝트 의 "조명" 버전이므로 "Apicurio"가 API의 Cryostat 인터페이스에 표시됩니다.

2. New API 를 클릭합니다. 새 API 페이지가 열립니다.

   기본적으로 API Builder는 OpenAPI 3 사양을 사용합니다. OpenAPI 2 사양을 사용하려면 새 API 버튼 옆에 있는 화살표를 클릭한 다음 OpenAPI 2 를 선택합니다.

   참고

   OpenAPI 2 사양을 기반으로 API를 여는 경우, API desktop의 Convert를 OpenAPI 3 옵션으로 사용하여 API 를 변환하여 OpenAPI 3 사양을 준수할 수 있습니다.

3. API 이름을 변경하려면 다음을 수행합니다.

   1. 커서를 이름 위에 마우스로 이동한 다음 표시되는 편집 아이콘( )을 클릭합니다.
   2. 이름을 편집합니다. 예를 들어 Task API 를 입력합니다.
   3. 확인 표시 아이콘을 클릭하여 이름 변경을 확인합니다.

4. 선택적으로 다음을 수행합니다.

   • 버전 번호 및 설명을 입력합니다.
   • 연락처 정보를 추가합니다(이름, 이메일 주소, URL).
   • 라이센스를 선택합니다.
   • 태그를 정의합니다.
   • 하나 이상의 서버를 정의합니다.
   • 보안 스키마를 구성합니다.
   • 보안 요구 사항을 지정합니다.

5. API의 각 개별 끝점에 대한 상대 경로를 정의합니다. 필드 이름은 슬래시(/)로 시작해야 합니다.

   작업 관리 API 예제에 대해 다음 두 경로를 생성합니다.

   • 작업 경로: /todo

   • ID별 특정 작업의 경로: /todo/{id}

     

6. 경로 매개변수 유형을 지정합니다.

   예제 id 매개변수의 경우:

   1. 경로 목록에서 /todo/{id} 를 클릭합니다.

      id 매개변수는 PATH PARAMETERS 섹션에 표시됩니다.

   2. 생성을 클릭합니다.
   3. description: 찾을 작업의 ID를 입력합니다.

   4. 유형에 대해 정수를 32bit 정수 로 선택합니다.

      

7. 데이터 유형 섹션에서 API에 재사용 가능한 유형을 정의합니다.

   1. 데이터 유형 추가를 클릭합니다.
   2. 데이터 유형 추가 대화 상자에서 이름을 입력합니다. 작업 관리 API 예제에 대해 Todo 를 입력합니다.

   3. 선택적으로 API window가 데이터 형식의 스키마를 생성하는 예제를 제공할 수 있습니다. 그런 다음 생성된 스키마를 편집할 수 있습니다.

      작업 관리 API 예제의 경우 다음 JSON 예제로 시작합니다.

      {
          "id": 1,
          "task": "my task",
          "completed": false
      }

   4. 선택적으로 데이터 유형으로 REST 리소스를 생성하도록 선택할 수 있습니다.

   5. 저장을 클릭합니다. 예제를 제공한 경우 API window는 다음 예제에서 스키마를 생성합니다.

      
8. 선택적으로 스키마 속성 편집을 추가하고 새 속성을 추가할 수 있습니다.Optionally, you can add edit the schema properties and add new ones.

9. Task Management API 예제의 경우 문자열 형식의 task 라는 하나의 속성을 사용하여 Task 라는 다른 데이터 유형을 생성합니다.

   

10. 각 경로에 대해 작업(GET, PUT, POST, DELETE, OPTIONS, HEAD 또는 PATCH)을 정의합니다.

    작업 관리 API 예제의 경우 다음 표에 설명된 대로 작업을 정의합니다.

    표 3.1. 작업 관리 API 작업

    경로	작업	설명	요청 본문	응답
    /todo	POST	새 작업을 생성합니다.	미디어 유형: 애플리케이션/json 데이터 유형: Task	상태 코드: 201 설명: 생성된 작업 응답 본문: 미디어 유형: application/json 데이터 유형: Todo
    /todo	GET	모든 작업을 가져옵니다.	해당 없음	상태 코드: 200 설명: 작업이 삭제됨 상태 코드: 400 설명: 작업이 삭제되지 않음
    /todo/{id}	GET	ID로 작업을 가져옵니다.	해당 없음	상태 코드: 200 설명: ID 응답 본문에 대해 발견된 작업: 미디어 유형: application/json 데이터 유형: Task 상태 코드: 404 description: no task with provided identifier found.
    /todo/{id}	UPDATE	작업을 ID로 업데이트합니다.	요청 본문 유형: Task	상태 코드: 200 설명: 완료됨 상태 코드: 400 설명: 작업이 업데이트되지 않음
    /todo/{id}	DELETE	ID로 작업을 삭제합니다.	해당 없음	상태 코드: 200 설명: 작업이 삭제됨 상태 코드: 400 설명: 작업이 삭제되지 않음

11. API Splunk의 유효성 검사 문제에 설명된 대로 모든 문제를 해결합니다.

12. OpenShift의 Fuse 전용의 경우 Save As 를 클릭한 다음 JSON 또는 YAML 형식을 선택하여 API 사양을 저장합니다.

    JSON 또는 YAML 파일이 로컬 다운로드 폴더에 다운로드됩니다. 기본 파일 이름은 적절한 파일 확장자가 있는 openapi-spec 입니다.