...
...
No período de migração das implementações em XML para JSON, será necessário que os formatos convivam simultaneamente e sejam interoperáveis.Isso implica que a modelagem de uma transação usando o padrão REST/JSON seja compatível com a modelagem usando o padrão SOAP/XML (orientações no tópico seguinte).
Assim que todos os ERPs forem capazes de trabalhar com a nova proposta, o formato XML e os endpoints SOAP poderão ser desativados.
...
O desenho de uma transação, no formato REST/JSON, deve utilizar o formato OpenAPI (anteriormente chamado Swagger), versão 3.0 em diante, em substituição ao formato XML Schema (XSD), utilizado na implementação SOAP/XML. Para mais informações sobre como implementar um documento Swagger, consulte a especificação própria do padrão.
Para a documentação da transação no arquivo de definição OpenAPI, há regras para a mensagem e para os campos, conforme abaixo:
Em nome da consistência entre os formatos, é necessário ter em mente o seguinte procedimento: ao desenvolver, por exemplo, um documento OpenAPI (padrão REST/JSON) para a transação CostCenter, versão 2.000, deve-se verificar se já existe um documento XSD da referida transação (padrão SOAP/XML). Existindo o documento, todos os atributos que definem a tag BusinessContent devem estar presentes no documento OpenAPI, para que o modelo seja considerado como sendo da transação CostCenter, versão 2.000.
Por outro lado, é possível que um documento OpenAPI seja implementado sem que haja o correspondente em XSD. Neste caso, a modelagem deve ser elaborada considerando que a transação também pode vir a ser usada no futuro, para integração server-to-server, e por isso, deve conter atributos que permitam o uso em tal contexto, mesmo que inicialmente a utilização seja no contexto client-to-server. Se isso for levado em consideração, não será necessário criar um documento XSD equivalente para a mesma transação e versão.
Para a documentação da transação no arquivo de definição OpenAPI, há regras para a mensagem e para os campos, conforme abaixo:
...
Informações |
---|
Este exemplo foi reduzido para destacar a definição do modelo de dados. Entretanto, um modelo completo deve incluir, entre outras coisas, os verbos HTTP suportados pela API e a documentação da mensagem conforme indicado anteriorementeanteriormente. |
Bloco de código | ||
---|---|---|
| ||
{ "openapi": "3.0.0", "info": { "description": "Centro de Custo", "version": '"2.000'", "title": "CostCenter", "contact": { "name": "T-Talk" } }, "paths": {}, "servers": [ { - "url": '"http://api.totvs.com.br/' components: schemas: CostCenter: type: object required: - Code - Name - ShortCode properties: CompanyId: type: string description: Código da empresa BranchId: type: string description: " } ], "components": { "schemas": { "CostCenter": { "type": "object", "required": [ "Code", "Name", "ShortCode" ], "properties": { "CompanyId": { "type": "string", "description": "Código da empresa", "maxLength": 3 }, "BranchId": { "type": "string", "description": "Código da filial/estabelecimento/coligada" CompanyInternalId: type: string description: }, "CompanyInternalId": { "type": "string", "description": "InternalId da empresa" Code: type: string description: }, "Code": { "type": "string", "description": "Código do centro de custo" InternalId: type: string description: }, "InternalId": { "type": "string", "description": "InternalId do centro de custo" RegisterSituation: type: string description: }, "RegisterSituation": { "type": "string", "description": "Indica se o centro de custo está ativo ou não.", "enum": [ "Active", "Inactive" ] }, "Name": { enum: - Active - Inactive Name: type: string description: Descrição do centro de custo ShortCode: type: string description: Descrição breve do centro de custo SPED: type: boolean Class: type: number"type": "string", "description": "Descrição do centro de custo", "maxLength": 100 }, "ShortCode": { "type": "string", "description": "RM: Código reduzido do centro de custo" }, "SPED": { "type": "boolean", "description": "Define se o centro de custo será enviado para SPED" }, "Class": { "type": "number", "format": "int8", "description": "Classe (Analítico ou Sintético)", "enum": [ 1, 2 ] } } }, "ListOfInternalId": { "type": "object", "properties": { "ListOfInternalId": { "type": "array", "items": { "required": [ "Destination", "Name", "Origin" ], "type": "object", "properties": { "Name": { "type": "string" }, "Origin": { "type": "string" }, "Destination": { "type": "string" } } } } }, "example": "{\n \"ListOfInternalId\": [{\n \"Name\": \"InternalId\",\n \"Origin\": \"Valor1\",\n \"Destination\": \"Valor2\"\n }]\n}" } } } } |