Fosrestbundle: Geração de documentação da API REST fora das rotas

Confira o http://getfrapi.com/ screencast para alguma inspiração.

Eu já vi. Mas eu não gosto de muitas coisas em sua realização. Primeiro de tudo, o REST deles não é RESTful :-D

"inspiração" e eu não estava falando sobre o descanso deles, mas sobre a geração de documentos (e testes) :)

Eu pessoalmente não gosto, mas poderíamos discutir a geração da documentação no formato WADL?

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

Gostaria de saber se uma direção melhor do que a geração seria fornecer alguns auxiliares de visualização que permitissem a construção rápida de controladores/visualizações de documentação. Isso parece melhor do que simplesmente gerar uma estrutura e seria mais extensível/manutenível. Em outras palavras, acho que gerar documentos de API funciona muito bem para o caso de uso do FRAPI (entre em um aplicativo), mas questiono se precisamos desse recurso "como está" ou se faz sentido.

Estamos falando de documentação para os clientes?

Tenha em mente que é isso que REST tenta evitar :)

odino: claro. mas há coisas como o fato de que mesmo se você seguir o HATEAOS você precisa inspecionar os cabeçalhos. também, embora você deva saber esperar códigos de status diferentes, ainda é bom saber quais códigos de status são "mais prováveis". é bom para uma revisão casual da API.

também outro tópico que deve ser ignorado: alguns clientes gostam de matar árvores e é bom não ter que perder muito tempo preenchendo essas páginas de papel :)

concordo, a única coisa que devemos evitar é confiar fortemente na documentação gerada, caso contrário, replicaríamos o WSDL

polegares para baixo para matadores de árvores :)

Até onde eu sei, os verdadeiros documentos da API REST são sobre a definição de tipos de mídia e suas relações, não URLs. Por exemplo, http://kenai.com/projects/suncloudapis/pages/Home , http://amundsen.com/media-types/collection/

Mas para APIs HTTP simples, que será o caso de 80% dos projetos da web, esse recurso ainda seria útil.

Sim vladar, os modelos de URI são obviamente maus. Mas se precisarmos desenvolver um pacote REST, devemos seguir esses princípios.

Um modelo de URI se encaixaria bem em um ApiBundle

Pode ser capaz de tirar conceitos de http://swagger.wordnik.com/

:+1: para Swagger. Isso parece incrível!

Para criar uma experiência semelhante, podemos ser capazes de:

• Métodos de análise marcados como @apidoc ou algo assim
• Obter descrição do método e parâmetros do docblock em métodos marcados @apidoc
• Permitir testes em linha de chamadas por ação.

Em suma, acho que alcançar telas como Swagger é bastante viável e faz muito sentido para este pacote.

Outra opção seria simplesmente gerar o JSON que o Swagger consome mas que vem com algum peso (Java)... Prefiro ver uma implementação "like".

Gerar JSON compatível foi meu primeiro pensamento. Vou cavar um pouco mais fundo no fim de semana, talvez haja alguma prototipagem rápida e suja possível.

@pminnieur parece que poderíamos facilmente fornecer a mesma funcionalidade básica em vez de integrar.

Pelo menos poderia funcionar como https://github.com/FriendsOfSymfony/FOSJsRoutingBundle - apenas adicionando alguns HTML/CSS sofisticados e expor suas rotas RESTful com algum tipo de documentação de API. Talvez pudéssemos usar algumas anotações para dar suporte a mais informações.

Eu gostaria de começar com isso, mas acho que seria melhor colocar o código em um pacote dedicado (por exemplo, FOSRestAPIExplorerBundle). A questão é: devemos oferecer suporte apenas à API Swagger (para que o Swagger seja usado para visualizar as informações coletadas e expostas em JSON) ou devemos fornecer nossa própria interface web também?

um pacote separado parece uma boa ideia. se apoiarmos apenas o swagger, talvez queiramos dizer isso no nome do pacote. não sei se também queremos apoiar outra coisa. depende da sua motivação e da qualidade da arrogância. uma pergunta sobre swagger: como isso funciona com APIs internas que não se deseja expor a um serviço externo?

Eu acho que você simplesmente tem que não tornar a URL retornando o Swagger JSON público se você não quiser que ele seja público ... :D Sério, eu gostaria de usar anotações e se você não quiser que uma rota seja public, você não adicionará a anotação @Expose() ou adicionará @Expose(false) -- algo assim. Assim como o FOSJsRoutingBundle é configurável como lidar com isso (expor tudo por padrão ou expor a lista de permissões). Se você quer dizer "aqui está um link para nossa API pública e este link é apenas para você", podemos adicionar uma anotação como @Api("public") e @Api("private") incluindo o componente de segurança para que você possa distribuir APIs diferentes documentações para diferentes pessoas (e controlar o acesso a elas).

Para o nome: gostaria de ter um nome genérico, Swagger seria o primeiro serviço de documentação da API a ser suportado. Se as pessoas quiserem adicionar qualquer outro serviço, elas podem simplesmente fazê-lo (e não devem começar do zero). @odino, por exemplo, poderia adicionar o suporte WADL. Pelo menos eu gostaria de fornecer uma interface web também.

Eu criei um repositório GitHub até agora para coletar ideias e problemas antes de começarmos. Sinta-se à vontade para abrir questões para quaisquer perguntas ou tópicos para discutir (a nomeação também pode ser discutida, com certeza) ;-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

tudo bem. uma vez que as coisas se ajeitem .. podemos movê-lo para o FOS

Você está planejando aproveitar https://github.com/wordnik/swagger-ui como o "exibidor"?

em primeiro lugar, sim. apenas gere json conforme a especificação do swagger para ser usado pelo swagger-ui.

fechamento em favor de https://github.com/nelmio/NelmioApiDocBundle

Eu sei que isso é muito antigo, mas algumas coisas mudaram desde então e eu encontrei isso relativamente rápido enquanto procurava um pacote/pacote para Swagger / Openapi.
Alguma chance de reconsiderar isso? Já que o NelmioApiDocBundle está abandonado e não consigo ver nenhuma alternativa real que se integre ao Symfony para Swagger/OpenApi (ou qualquer outro realmente, RAML,...?).