Uma API REST deve gastar quase todo o seu esforço descritivo na definição do (s) tipo (s) de mídia usado (s) para representar recursos e conduzir o estado da aplicação. Existem várias abordagens para a documentação da API. Este documento apresenta algumas das várias ferramentas e opções que você pode escolher. As abordagens não devem ser consideradas exclusivas - você pode querer fornecer mais de um estilo de documentação para sua API, como uma API auto-descrevente que também inclui documentação estática dos vários pontos finais da API. A maneira mais comum de documentar as APIs da Web hoje é produzir documentação que lista os pontos finais da API textualmente e descreve as operações permitidas em cada uma. Existem várias ferramentas que permitem que você faça isso de forma automatizada ou semi-automatizada. O DRF Docs permite documentar as APIs da Web feitas com o Django REST Framework e é autoria da Emmanouil Konstantinidis. É feito para trabalhar fora da caixa e sua configuração não deve demorar mais do que alguns minutos. A documentação completa pode ser encontrada no site enquanto há também uma demo disponível para que as pessoas vejam o que parece. Os pontos de extremidade da API ao vivo permitem que você utilize os pontos finais da documentação de forma limpa. Os recursos incluem a personalização do modelo com a marca, as configurações para ocultar os documentos, dependendo do ambiente e muito mais. Tanto este pacote quanto o Django REST Swagger estão totalmente documentados, bem suportados e são altamente recomendados. Marc Gibbons Django REST Swagger integra o framework REST com a ferramenta de documentação da Swagger API. O pacote produz documentação API bem apresentada e inclui ferramentas interativas para testar pontos de extremidade da API. O Django REST Swagger suporta versões de estrutura REST 2.3 e acima. Mark também é o autor do pacote REST Framework Docs que oferece documentação autogenerada limpa e simples para sua API, mas está obsoleta e mudou-se para o Django REST Swagger. Tanto este pacote quanto os documentos DRF estão totalmente documentados, bem suportados e são altamente recomendados. Oleksander Mashianovs DRF Auto Docs automatizado api renderer. Coleta quase todo o código que você escreveu na documentação sem esforço. Visualização funcional docs estrutura semelhante a uma árvore Docstrings: markdown preservar espaço amplificador formatação de novas linhas com sintaxe agradável Campos: opções de renderização do texto de ajuda (para especificar a saída do SerializerMethodField, etc.) renderização inteligente readonlyrequired Propriedades do ponto final: filtersbackends authenticationclasses permissionsclasses params extras (pars GET) Existem vários Outras ferramentas e serviços on-line para fornecer a documentação da API. Um serviço notável é Apiary. Com o Apiary, você descreve sua API usando uma sintaxe de tipo simples como marca. A documentação gerada inclui a interação da API, um servidor simulado para teste de prototipagem de amplificador e várias outras ferramentas. A API navegável que a estrutura REST fornece torna possível que sua API seja totalmente auto-descrevente. A documentação para cada ponto final da API pode ser fornecida simplesmente visitando o URL em seu navegador. O título que é usado na API navegável é gerado a partir do nome da classe de exibição ou nome da função. Qualquer sufixo View ou ViewSet está despojado, e a seqüência de caracteres é espaços em branco separados em limites ou sublinhados de maiúsculas ou minúsculas. Por exemplo, a exibição UserListView. Será denominado Lista de Usuários quando apresentado na API navegável. Ao trabalhar com conjuntos de visualizações, um sufixo apropriado é anexado a cada visualização gerada. Por exemplo, a exibição definida pelo UserViewSet gerará exibições denominadas Lista de Usuários e Instância de Usuário. A descrição na API navegável é gerada a partir do docstring da vista ou do viewet. Se a biblioteca de redução de python estiver instalada, a sintaxe do markdown pode ser usada na docstring e será convertida em HTML na API navegável. Por exemplo: Note que, ao usar conjuntos de visualizações, o docstring básico é usado para todas as visualizações geradas. Para fornecer descrições para cada visualização, como para a lista e recuperar visualizações, use seções docstring como descrito em Esquemas como documentação: Exemplos. As APIs do framework REST também oferecem suporte a descrições programáticas acessíveis, usando o método OPTIONS HTTP. Uma visualização responderá a uma solicitação OPTIONS com metadados, incluindo o nome, a descrição e os vários tipos de mídia que aceita e responde. Ao usar as visualizações genéricas, quaisquer solicitações OPTIONS responderão adicionalmente com metadados sobre quaisquer ações POST ou PUT disponíveis, descrevendo quais campos estão no serializador. Você pode modificar o comportamento de resposta para solicitações OPTIONS, substituindo o método de exibição de metadados. Por exemplo: Para ser completamente RESTful, uma API deve apresentar suas ações disponíveis como controles hipermídia nas respostas que ela envia. Nessa abordagem, em vez de documentar os pontos de extremidade da API disponíveis na frente, a descrição concentra-se nos tipos de mídia que são usados. As ações disponíveis que podem ser tomadas em qualquer URL especificado não são estritamente corrigidas, mas são disponibilizadas pela presença de controles de link e formulário no documento retornado. Para implementar uma API hipermedia, você precisará decidir sobre um tipo de mídia apropriado para a API e implementar um processador e analisador personalizado para esse tipo de mídia. A seção REST, Hypermedia amp HATEOAS da documentação inclui ponteiros para leitura em segundo plano, bem como links para vários formatos hipermídia. Documentação construída com o modelo MkDocs. API. Um poderoso linguagem de descrição de API de alto nível para APIs da web. API Blueprint é simples e acessível a todos os envolvidos no ciclo de vida da API. Sua sintaxe é concisa ainda expressiva. Com o API Blueprint, você pode criar e criar protótipos de APIs para serem criados ou documentar e testar as APIs de missão crítica já implantadas. Focada no API do Collaboration, o Blueprint é construído para incentivar o diálogo e a colaboração entre as partes interessadas do projeto, desenvolvedores e clientes em qualquer ponto do ciclo de vida da API. Ao mesmo tempo, as ferramentas da API Blueprint fornecem o suporte para alcançar os objetivos, seja o desenvolvimento, a governança ou a entrega da API. API Blueprint é completamente aberto sob a licença MIT. O seu futuro é transparente e aberto. API Blueprint não precisa de um grupo de trabalho fechado. Em vez disso, ele usa o processo RFC semelhante ao idioma Rust ou aos processos de RFC da proposta de aprimoramento do Django. Em casa no GitHub O idioma da API Blueprint é reconhecido pelo GitHub. Procure o Blueprint da API no GitHub usando o idioma: consulta do Blueprint da API. O tipo de mídia para API Blueprint é textvnd. apiblueprint. E a extensão de arquivo padrão é. apib. Se você usa esta extensão, seus planos no GitHub obterão sintaxe. Construído para melhor API Designs API O Blueprint é construído para encorajar melhores designs da API através da abstração. O objetivo do API Blueprint é desacoplar elementos da API para permitir a modularidade enquanto encapsulam o comportamento de implementação do backend. Por exemplo, modelo seus dados primeiro usando a sintaxe de descrição de dados. Em seguida, use e reutilize os dados em seus pontos finais da API. Design-first API Blueprint é tudo sobre a filosofia design-first. Semelhante aos testes no desenvolvimento orientado por teste, o API Blueprint representa um contrato para uma API. Discutir sua API e estabelecer o contrato antes do desenvolvimento tende a levar a melhores projetos de API. Uma vez que o seu Blueprint da API está no lugar, todos podem testar se a implementação está de acordo com as expectativas estabelecidas no contrato. Ferramentas incríveis Graças à sua ampla adoção, há uma infinidade de ferramentas criadas para API Blueprint. De várias ferramentas autônomas, como ferramentas simuladas de servidor, documentação e teste, para soluções de ciclo de vida de API completas. Consulte a seção Ferramentas para a lista. Primeiros passos Para começar com o Blueprint da API, você precisará de um editor de texto simples. Para a melhor experiência de edição, altere a sintaxe-destaque para Markdown ou diretamente para API Blueprint (se suportado pelo seu editor). Depois de escrever o seu primeiro modelo de API, você pode discutir o design da API com amigos e usar as ferramentas para o Blueprint da API. Por exemplo, para renderizar documentação, gerar uma simulação de seu serviço ou começar a testar sua implementação do backend. Verifique a seção Documentação para obter recursos adicionais na sintaxe Blueprint da API.
No comments:
Post a Comment