Fosrestbundle: 경로에서 REST API 문서 생성

영감을 얻으려면 http://getfrapi.com/ screencast를 확인하십시오.

나는 이미 그것을 보았다. 그러나 나는 그들의 실현에서 많은 것을 좋아하지 않습니다. 우선, 그들의 REST는 RESTful이 아닙니다 :-D

"영감"이고 나는 그들의 휴식이 아니라 그들의 문서(및 테스트) 세대에 대해 이야기하고 있었습니다. :)

개인적으로 마음에 들지 않지만 WADL 형식의 문서 생성에 대해 논의할 수 있습니까?

http://www.w3.org/Submission/wadl/

문서 컨트롤러/뷰를 빠르게 구축할 수 있는 뷰 도우미를 제공하는 것이 세대보다 더 나은 방향인지 궁금합니다. 이것은 단순히 구조를 생성하는 것보다 더 나은 것으로 보이며 더 확장 가능하고 유지 관리할 수 있습니다. 즉, API 문서를 생성하는 것이 FRAPI의 사용 사례(앱에 드롭)에 적합하지만 이 기능이 "있는 그대로" 필요한지 또는 의미가 있는지에 대한 질문입니다.

고객을 위한 문서에 대해 이야기하고 있습니까?

이것이 REST가 피하려고 하는 것임을 명심하십시오. :)

오디노: 물론이죠. 그러나 HATEAOS를 따르더라도 헤더를 검사해야 한다는 사실과 같은 것들이 있습니다. 또한 다른 상태 코드가 예상되는 것을 알아야 하지만 어떤 상태 코드가 "더 가능성이 높은"지 아는 것이 좋습니다. API의 캐주얼한 검토에 좋습니다.

또한 무시해야 하는 또 다른 주제: 일부 클라이언트는 나무를 죽이는 것과 같으며 이 페이지를 채우는 데 많은 시간을 낭비할 필요가 없습니다. :)

동의합니다. 우리가 피해야 할 유일한 것은 생성된 문서에 크게 의존하는 것입니다. 그렇지 않으면 WSDL을 복제합니다.

나무를 죽이는 사람들을 위해 엄지 손가락을 아래로 내리십시오 :)

내가 아는 한, 진정한 REST API 문서는 URL이 아니라 미디어 유형과 그 관계를 정의하는 것입니다. 예: http://kenai.com/projects/suncloudapis/pages/Home , http://amundsen.com/media-types/collection/

그러나 웹 프로젝트의 80%에 해당하는 간단한 HTTP API의 경우 이 기능이 여전히 유용할 것입니다.

네 vladar, URI 템플릿은 분명히 악합니다. 그러나 REST 번들을 개발해야 하는 경우 이러한 원칙을 따라야 합니다.

URI 템플릿은 ApiBundle에 적합합니다.

http://swagger.wordnik.com/ 에서 개념을 가져올 수 있습니다.

:+1: 스웨거로. 이것은 멋진 것 같습니다!

유사한 경험을 만들기 위해 다음을 수행할 수 있습니다.

• @apidoc 또는 기타로 표시된 구문 분석 방법
• @apidoc 표시된 메소드의 docblock에서 메소드 및 매개변수에 대한 설명 가져오기
• 작업별로 호출의 인라인 테스트를 허용합니다.

대체로 Swagger와 같은 화면을 구현하는 것은 꽤 할 수 있고 이 번들에 대해 많은 의미가 있다고 생각합니다.

또 다른 옵션은 단순히 Swagger가 소비하지만 약간의 가중치(Java)와 함께 제공되는 JSON을 생성하는 것입니다. 차라리 "like" 구현을 보고 싶습니다.

호환 가능한 JSON을 생성하는 것이 첫 번째 생각이었습니다. 나는 주말에 조금 더 깊이 파고들 것입니다. 아마도 빠른 'n 더러운 프로토타이핑이 가능할 것입니다.

@pminnieur 는 통합보다는 동일한 기본 기능을 쉽게 제공할 수 있을 것 같습니다.

최소한 https://github.com/FriendsOfSymfony/FOSJsRoutingBundle 처럼 작동할 수 있습니다. 멋진 HTML/CSS를 추가하고 일종의 API 문서로 RESTful 경로를 노출하기만 하면 됩니다. 더 많은 정보를 지원하기 위해 일부 주석을 사용할 수 있습니다.

이것으로 시작하고 싶지만 코드를 전용 번들(예: FOSRestAPIExplorerBundle)에 넣는 것이 더 나을 것이라고 생각합니다. 문제는 Swagger API만 지원해야 합니까(따라서 Swagger는 JSON으로 수집 및 노출되는 정보를 시각화하는 데 사용됨) 아니면 자체 웹 인터페이스도 제공해야 합니까?

별도의 번들은 좋은 생각인 것 같습니다. 우리가 swagger를 지원한다면 번들 이름에서 그렇게 말하고 싶을 것입니다. 우리도 다른 것을 지원하고 싶은지 모르겠습니다. 당신의 동기와 스웨거의 질에 달려 있습니다. swagger에 대한 한 가지 질문: 외부 서비스에 노출하고 싶지 않은 내부 API와 어떻게 작동합니까?

공개하지 않으려면 Swagger JSON을 반환하는 URL을 공개하지 않아야한다고 생각합니다 ... :D 진심으로, 주석을 사용하고 경로를 원하지 않는 경우 public의 경우 @Expose() 주석을 추가하거나 @Expose(false) 를 추가하지 않습니다. -- 이와 같은 것입니다. FOSJsRoutingBundle과 마찬가지로 처리 방법을 구성할 수 있습니다(기본적으로 모든 것을 노출하거나 화이트리스트를 노출). "여기에 공개 API에 대한 링크가 있으며 이 링크는 귀하만을 위한 것입니다"라는 의미인 경우 보안 구성 요소를 포함하여 @Api("public") 및 @Api("private") $와 같은 주석을 추가하여 다른 API를 배포할 수 있습니다. 다른 사람들에게 문서를 제공하고 그들에 대한 액세스를 제어합니다.

이름의 경우: 일반 이름을 갖고 싶습니다. Swagger는 지원되는 첫 번째 API 문서 서비스가 될 것입니다. 사람들이 다른 서비스를 추가하고 싶다면 그냥 할 수 있습니다(처음부터 시작해서는 안 됨). 예를 들어 @odino 는 WADL 지원을 추가할 수 있습니다. 최소한 웹 인터페이스도 제공하고 싶습니다.

시작하기 전에 아이디어와 문제를 수집하기 위해 지금까지 GitHub 저장소를 만들었습니다. 토론할 질문이나 주제에 대한 문제를 자유롭게 여십시오(이름 지정도 논의할 수 있음) ;-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

그래 좋아. 일단 상황이 형성되면 .. FOS로 이동할 수 있습니다.

https://github.com/wordnik/swagger-ui 를 "디스플레이"로 활용할 계획입니까?

우선, 그렇습니다. swagger-ui에서 사용할 swagger-spec 준수 json만 생성합니다.

https://github.com/nelmio/NelmioApiDocBundle 에 찬성하여 마감

나는 이것이 매우 오래되었다는 것을 알고 있지만 그 이후로 몇 가지 사항이 변경되었으며 Swagger / Openapi용 패키지/번들을 찾는 동안 비교적 빨리 발견했습니다.
이것을 재고할 기회가 있습니까? NelmioApiDocBundle이 버려지고 Symfony for Swagger/OpenApi(또는 다른 모든 RAML, ...?)에 통합되는 실제 대안을 볼 수 없기 때문입니다.