국비학원 43일차 : Spring Boot_5, API명세서

@Query

JPQL (Java Persistence Query Language)
SQL과 유사한 문법을 가지지만, 엔티티 클래스와 그 필드를 기반으로 쿼리를 작성한다.

Native SQL
데이터베이스의 각 SQL 문법을 그대로 따르는 방식이다. nativeQuery 속성을 true로 설정해야 한다.

RestApiServiceImplement

//@Component //Ioc 이용한 DI사용가능하다
@Service // Component와 동일한데 이름을 정확하게 지정해주는것
public class RestApiServiceImplement implements RestAPIService { //구현체
    
    ⭐private ExampleRepository exampleRepository;

    @Autowired
    public RestApiServiceImplement(ExampleRepository exampleRepository){
        this.exampleRepository = exampleRepository;
    }

⭐Repository의 상위는 Service, 그래서 Repository의 호출은 Service에서한다.
(구현은 implements)

1. 데이터 삽입

    public String postMethod(){
        // 데이터 삽입
        // 1. Entity 인스턴스(= 데이터 베이스 테이블의 레코드) 생성 
        ExampleEntity exampleEntity = 
            ExampleEntity.builder()
            .exampleColumn2("string1")
            .exampleColumn3(false)
            .build();

        // 2. Repository를 거쳐서 Entity 인스턴스를 저장
        exampleRepository.save(exampleEntity);

        return null;
    }

포스트맨에서 POST 'http://localhost:4040/api/post-method' 하면
우리가 연결한 SQL DB에 추가가 되게 된다.

2. 데이터 조회

    public String getMethod(){
        //데이터 조회
        // 1. jpaRepository에 있는 findBy 메서드로 Entity 조회
        //ExampleEntity exampleEntity = exampleRepository.findById(1).get();

        ExampleEntity exampleEntity = exampleRepository.findByPk(1);


        return exampleEntity == null ? "null" : exampleEntity.toString(); 
        //반환을 String으로 설정해뒀으니까
        //null인 경우를 예외처리 해줌
    }

우리가 보고자 하는 값의 정보 입력하면 포스트맨에서 확인할수 있다.

3. 데이터 수정

    public String patchMethod(){
        //데이터 수정
        //patch (구분자와 변경할 값만 있으면 된다)
        // 1-1. 특정 조건으로 Entity 조회 
        ExampleEntity exampleEntity = exampleRepository.findById(1).get();
        // 1-2. 데이터 수정작업
        exampleEntity.setExampleColumn2("string2");
        // 1-3. Entity 인스턴스 저장
        exampleRepository.save(exampleEntity);

        //put (필수값은 전부 필요하다)
        // 2-1. Entity 인스턴스 생성
        ExampleEntity exampleEntity2 = new ExampleEntity(2, "string3",true); 
        //⭐입력받은 전체를 가져와 save
        //존재하는 테이블에 pk가 존재한다면 원래 있던 것을 변경시킨다
        // 2-2 Entity 인스턴스 저장
        exampleRepository.save(exampleEntity2);
        return null;
    }

patch 방법 결과

1번을 찾아와서 cloumn2의 값을 string2로 바꿨다.
put 방법 결과

2번을 string3으로 바꾸고 true로 바꾸는 모든 값을 지정해줬다.

4. 데이터 삭제

    public String deleteMethod(){
        //데이터 삭제
        // 1-1. jpaRepository애 있는 deleteBy메서드로 Entity 삭제
        exampleRepository.deleteById(1);
        //exampleRepository.delete(null); 
        //특정 레코드 자체를넣어도 지울수 있다.
        return null;
    }
}

1번의 값을 null로 바꿔서 삭제가 되었다.

1번을 조회하는 메서드 진행시 값을 가져오지 못함!

ExampleRepository

@Repository
public interface ExampleRepository extends
							JpaRepository<ExampleEntity, Integer>{
    
    //메서드 정의하는 공간에 규칙만 잘 따라서 작성하면 쿼리문 생성없이 바로 할 수있다.
    public ExampleEntity findByPk(int pk);
    public List<ExampleEntity>
    	🌷findByExampleColumn3AndExampleColumn2(//여러 조건 검색시 And사용해서 연결 
        	boolean exampleColumn3,String exampleColumn2);
			//매개변수의 순서에 맞춰서 입력해야한다!! 
            //데이터 타입도 순서에 맞게 잘 설정하기
    public boolean exexistsByExampleColumn3(boolean exampleColumn3); 
    			//이거하면 트랜잭션 에러가 뜬다? 처리는 다음에
                //해당 조건에 따라서 존재하는지 아닌지에 대한 반환하는 메서드                         

}

🌷findbyId처럼 직접적으로 원래 선언되어있는 형태를 쓰지않고
커스텀해서 사용하게 된다 (id를 찾지못해서 서버가 실행이 안되는 일이 없도록)

API 명세서

API 명세서(API Specification)는 Application Programming Interface(API)의 기능, 사용 방법, 엔드포인트, 요청 및 응답 형식, 인증 방법 등에 대한 상세한 정보를 제공하는 문서이다.

EndPoint
웹 API에서 클라이언트가 서버에 요청을 보내는 URL 주소를 의미합니다. 즉, 클라이언트가 요청하는 API의 기능이 정의된 주소를 말합니다.

GET /api/users/{id}

위 엔드포인트는 /api/users/ 다음에 {id}값을 넣어서 사용자 정보를 조회할 수 있는 API를 나타내고 있습니다. 클라이언트는 이 엔드포인트를 통해 사용자 정보를 조회할 수 있습니다.

또한, 엔드포인트는 HTTP 메서드와 함께 사용됩니다. HTTP 메서드는 클라이언트가 서버에 요청할 때 사용하는 메서드를 의미합니다. 예를 들어, GET 메서드는 서버에서 데이터를 조회할 때 사용하고, POST 메서드는 서버에 데이터를 전송할 때 사용합니다. 따라서, 엔드포인트와 함께 사용되는 HTTP 메서드에 따라 클라이언트의 요청 방식이 달라지게 됩니다.

API 명세서 작성 목적

개발자들이 API를 이해하고 올바르게 사용할 수 있도록 안내하는 것이다.

API 명세서 작성 항목

개요: API의 목적과 기능을 간략하게 설명한다. 이를 통해 사용자가 API의 적용 가능성을 파악할 수 있다.

엔드포인트: 사용 가능한 모든 엔드포인트를 나열하고, 각 엔드포인트의 기능, URL, 요청 방식(GET, POST, PUT, DELETE 등)을 설명한다.

인증: API를 사용하기 위한 인증 방식을 설명한다. 예를 들어, API 키 사용, OAuth 인증 등의 인증 방법에 대해 안내다.

요청 매개변수: 각 엔드포인트에 사용되는 요청 매개변수를 설명한다. 필수 매개변수와 선택적 매개변수를 구분하고, 데이터 타입, 제약 사항, 기본값 등을 명시한다.

요청 예시: 각 엔드포인트에 대한 실제 요청 예시를 제공한다. 사용자가 쉽게 이해하고 따라할 수 있는 코드 예제를 제공하는 것이 좋다.

응답 형식: API 응답의 형식과 구조를 설명한다. 일반적으로 JSON 형식을 사용하며, 각 필드의 의미와 데이터 타입을 명시한다.

응답 예시: 각 엔드포인트에 대한 실제 응답 예시를 제공한다. 사용자가 결과를 쉽게 이해하고 예상할 수 있도록 도와준다.

오류 코드 및 메시지: 발생 가능한 오류 코드와 그에 대한 설명을 제공한다. 사용자가 오류 상황을 쉽게 파악하고 대처할 수 있도록 도와준다. 잘못된 걸 받았을적에 처리할수 있도록 다 설명을 해줘서 보내줘야한다.

버전 관리: API의 버전 정보를 명시하고, 버전 업데이트 시 변경 사항을 문서에 반영한다. 이를 통해 사용자가 API의 업데이트 상황을 파악할 수 있다. api 작성된 날짜까지 작성해주는게 좋다.

연락처 정보: API 관련 문의를 할 수 있는 연락처 정보를 제공다. 이메일, 전화번호, 웹사이트 등이 포함될 수 있다.

API작성 데이터 타입

Java에서의 데이터 타입으로 적으면 안된다. String, Number, Boolean형태만 존재한다. json타입따라야한다)