마지막으로, 더 이상 문서를 작성하기 위해 열심히 노력할 필요가 없습니다! 디버깅 가능한 API 문서를 생성하는 방법을 가르쳐주세요.

이 기사는 무엇에 관한 것입니까?

저는 항상 문서를 작성해야 해요. 작성하지 않으면 코드를 유지할 수 없으므로 를 로 작성해야 합니다. 하지만 문서를 작성하는 일은 시간이 많이 걸리고 힘들고, 그리고 더 무서운 것은 책장에 놔두는 일이 여전히 너무 힘들다는 것입니다. 낭비, 정말 말할 수 없이 고통스럽습니다.

늘 '문서 작성'에 시달려왔는데 우연히 신같은 기사를 보고 자동화 도구와 DSL을 확인해보니 인터넷. 이론이 갑자기 깨달아졌습니다! 대부분은 이해하지 못하더라도 쉽게 좋은 문서를 작성하고 싶다면 그것만으로도 충분합니다!

이제 제가 어떻게 했는지 이야기해보겠습니다!

무엇을 해야 할까요?

우리의 궁극적인 목표는 좋은 문서를 작성하는 것입니다. 따라서 먼저 좋은 문서란 무엇인가를 결정해야 합니다.

좋은 문서는 아래와 같습니다.

위 문서의 어떤 점이 좋은가요?
첫째, 기능과 매개변수를 한눈에 알 수 있는 문서입니다.
둘째, 프로그램입니다. 매개변수를 입력하고 결과를 즉시 확인하세요.

그래서 제가 바라는 것은 코드를 완성한 후 위에서 언급한 것처럼 아주 적은 노력으로 디버깅 가능한 문서를 생성할 수 있다는 것입니다.

다음으로 두 가지 작업을 수행해야 합니다.
1. 문서 생성
2. 문서는 디버깅 가능합니다.

어떻게 하나요?

이제 시작하려고 하는데 여전히 시작할 수 없다는 느낌이 있으므로 가장 구체적인 것, 즉 현재 유일하게 눈에 보이는 디버깅 가능한 API부터 시작하겠습니다. .

어떤 종류의 디버깅 가능한 API를 만들까요?

이전 렌더링을 참고하면 단순화즉, 다음과 같습니다.

일반 텍스트에는 클래스 이름, 메소드, 함수 설명 및 입력 매개변수가 표시됩니다.
실행 버튼이 있고
실행 결과를 표시하는 영역이 있습니다.

이 인터페이스에서 변수는 무엇인가요?

수업명

목록 항목

메소드 이름

기능 설명

매개변수 개수

매개변수 이름

실행결과

그 중 API는 클래스 이름, 메소드 이름, 함수 설명, 여러 매개변수 이름에 해당하며 실행 후 실행 결과가 생성됩니다.

모델 분석

위 결과를 바탕으로 이 API를 모델 클래스로 추상화할 수 있습니다.

API에는 클래스 이름, 클래스 파일 경로, 메서드 이름, 함수 설명, 메서드에 입력해야 하는 매개변수 등의 속성이 포함됩니다.

매개변수에는 매개변수 이름 및 매개변수 설명과 같은 속성도 포함됩니다.

이벤트 스트림

다음으로 전체 거래 과정을 분석해 보겠습니다.

한 문장과정:
수업의 HTML 문서를 생성하려면 "생성" 버튼을 클릭하세요.
이것이 우리가 하고 싶은 일이지만 매우 불분명합니다. 특정 클래스의 특정 메소드에 해당하는 HTML 문서를 생성하고 싶지만 한 문장으로 명확한 설명이 없습니다.

이제 명확하게 설명하고 싶어서 문단으로 확장했습니다.
생성할 문서의 클래스와 메서드가 구성 파일에 지정되어 있습니다. 버튼" 을 누르고 구성 파일을 읽은 다음 문서를 순차적으로 생성합니다.
모든 단계가 명확해질 때까지 이러한 방식으로 계속 확장해 나갈 것입니다.

최종 디자인

전체 시스템에는 세 가지 유형의 페이지가 있습니다.
기능 페이지 : API를 생성하는 버튼은 하나만 있습니다.

클래스 목록 페이지: 클래스와 해당 메소드를 나열하면 API 페이지로 이동합니다.

API 페이지: 메소드 설명이 나열되며, 매개변수를 입력하고 메소드를 실행할 수 있으며, 실행 결과를 볼 수 있습니다.

세 가지 유형의 페이지 중 두 번째 유형의 목록 페이지는 기능이 없고 페이지 이동만 포함되어 있어 HTML만으로 구현이 가능합니다.
함수 페이지와 API 페이지는 MVC 패턴을 사용하여 디자인되었습니다.

기능 페이지

MVC 구조
모델:API;
보기:make_api_template.php;
컨트롤러:create_api.php

MVC 호출 프로세스
사용자가 뷰 레이어에서 "생성" 버튼을 클릭하면 컨트롤러가 트리거됩니다.
컨트롤러는 API를 생성해야 하는 클래스를 지정하고 make_api는 모델을 생성합니다.
컨트롤러는 이러한 모델을 사용하여 문서를 생성합니다

API 페이지

MVC 구조
모델: 아직 독립 모델을 구성하지 않은 js 코드
보기: 생성된 html 페이지;
컨트롤러: index.php

MVC 호출 프로세스
사용자는 뷰 레이어에 메소드의 매개변수를 입력하고 "실행" 버튼을 클릭하여 컨트롤러를 트리거합니다.
컨트롤러는 이를 기반으로 메소드를 실행합니다. View 페이지에서 매개변수가 전달되어 결과가 View로 반환됩니다.
View가 결과를 받아 표시합니다

결론

제가 구현한 버전은 CohenBible입니다.

prmd, swagger editor, apidocjs 등 유사한 도구가 많이 있으며 모두 매우 유용합니다.
이 글을 쓰는 것은 모든 사람이 바퀴를 재발명하도록 장려하려는 것이 아니지만 직접 구현하면 다른 이점을 얻을 수 있습니다.

왜 바퀴를 재발명하려고 생각할까요?
사실 가장 큰 이유는 위 도구들을 어떻게 사용하는지 잘 몰라서 제가 직접 구현하고 문서 생성 전 과정을 거쳐야 했다는 점입니다. 결과적으로 위의 도구들을 다시 살펴보면 실제로 바로 사용할 수 있게 되었습니다! 공식 튜토리얼을 따라하시면 ​​얼마나 시간이 걸릴지 모르겠네요, ㅎㅎ :)

아무리 어려워도 API를 사용하는 방법을 가르쳐주세요