Swagger no Magento 2: Explore suas API’s
Desenvolvimento, Magento 2
Publicado em 23 de junho de 2021
O Swagger no Magento facilita o trabalho de quem quer explorar as APIs da plataforma.
Ele permite que desenvolvedores e integradores, vejam todos os endpoints públicos e privados.
Além disso, com ele ainda é possível chamar praticamente qualquer API. E tudo isso à partir do navegador, como no exemplo abaixo:
Como acessar o Swagger no Magento?
Para isso, basta acessar <url-da-loja>/swagger ou <url-da-loja>/swagger?store=<codigo-da-store>.
No caso acima estou em https://pagseguro-exemplo-m2.ricardomartins.net.br/swagger?store=default. Onde default é o código da loja (store) que quero ver.
store=all
Ao fornecer o código all como parâmetro para store, todas as lojas serão afetadas. Isto se aplica a alterações nos módulos de CMS e Produtos.
Acessando APIs Privadas com Swagger
Algumas APIs precisam de permissões especiais para serem executadas ou mesmo visualizadas. O Swagger cuidará disso pra você depois que informar a chave de autorização no campo api_key.
Temos pelo menos dois grupos de APIs privadas no Magento 2: APIs de Clientes e APIs de Administradores
APIs de Clientes
São aquelas que nos permitem alterar dados cadastrais, visualizar itens no carrinho, escrever avaliações, etc.
Para gerar uma API Key de cliente, fazemos uma chamada à API /V1/integration/customer/token.
API de Administrador
Permitem cadastrar produtos, alterar cadastros de usuários, alterar estoque, etc
Para gerar uma API Key de cliente, fazemos uma chamada à API /V1/integration/admin/token.
Ou para /V1/tfa/provider/google/authenticate. No segundo caso, apenas quando temos autenticação de 2 fatores ativado (2FA). Se este for seu caso, veja uma imagem com exemplo desta chamada.
Da mesma forma que outras chamadas, esta também pode ser feita dentro do próprio swagger. Sendo assim, basta localizar a chamada integrationAdminTokenServiceV1 e clicar no link.
Desabilitando o Swagger no Magento
A fim de dificultar (levemente) que alguém explore suas APIs, você pode desabilitar o Swagger. Para isso, basta desabilitar os seguintes módulos:
- Magento_Swagger
- Magento_SwaggerWebapi
- Magento_SwaggerWebapiAsync
Ou seja, basta executar bin/magento module:disable Magento_Swagger Magento_SwaggerWebapi Magento_SwaggerWebapiAsync.
No entanto, note que isso não “esconderá” suas APIs totalmente. Um esquema delas ainda estará disponível em <sualoja.com>/rest/all/schema?services=all.
O próprio Magento e outros módulos utilizam várias destas API’s e elas não podem e nem devem ser desabilitadas.
Conclusão (e minha opinião sobre o Swagger)
Como resultado do que vimos aqui, o Swagger é uma mão na roda para quem quer ter um primeiro contato com as APIs do Magento.
No momento em que o acessamos, podemos ver todas as APIs REST disponíveis em uma loja Magento 2. Inclusive dos módulos de terceiro instalados.
No entanto, pessoalmente não acho prático usar o Swagger para realizar testes mais complexos. Ele é útil apenas para ter uma lista de APIs com alguma documentação adicional. É útil para módulos de terceiros que carecem de documentação. As APIs do core do Magento já possuem uma documentação oficial melhor que a fornecida por ele.
A fim de testar e consumir as APIs do Magento (ou qualquer outra), ainda prefiro usar o Postman.
Ele é um cliente desktop (ou web) onde podemos organizar e salvar nossas requisições. Bom, na verdade dá pra fazer muito mais que isso. Mas não vou esgotar o assunto aqui. 🙂
Exemplos de Uso das APIs REST do Magento
A fim de testar as APIs do Magento, você pode recorrer ao uso de coleções com exemplos de uso das APIs do Magento. Neste link existem alguns exemplos que podem ser importador no seu Postman e validados por mim.
A fim de ilustrar ainda mais, no meu Minicurso Magento 2 REST APIs, trago mais de 650 exemplos de uso das APIs. Mais de 100 destes, criados e organizados por mim. Tudo pra usar no Postman, e seguido de várias explicações, comentários e documentações.
Além disso, a gente aborda também as APIs em massa do Magento. As bulk apis nos permitem executar ações em massa. Ou seja, com uma única chamada é possível poupar até 1000 requisições para atualizar, inserir ou excluir registros.
Vale a pena conhecer este curso se você quer aprender a realizar integrações com Magento, ou simplesmente conhecer a fundo suas APIs.
Outras referências
Talvez você queira ver:
- Como usar a autenticação 2FA com API (Inglês)
- Documentação da API Magento (Inglês)
- Exemplos de uso das APIs Rest do Magento (Grátis)
- Primeira aula do curso de APIs
- APIs GraphQL do Magento: Entenda o Básico
- Exemplos de uso das APIs do Magento 1.x (SOAP)
- PagSeguro (PagBank) para Magento 1 recebe a Nova Geração - 9 de abril de 2024
- Recorrência no WooCommerce Sem Plugins Pagos - 28 de janeiro de 2024
- Chargeback. O que é, e como se livrar deles. - 19 de dezembro de 2023
Deixe seu comentário
[fbcomments url="https://www.magenteiro.com/blog/magento-2/swagger-no-magento-2-apis/"]