...
O desenho de uma transação, no formato REST/JSON, deve utilizar o formato OpenAPI (anteriormente chamado Swagger), versão 3.0 em dianteJson Schema, Draft 4 ou superior, em substituição ao formato XML Schema (XSD) , utilizado na implementação SOAP/XML. Para mais informações sobre como implementar um documento Swagger, no formato Json Schema consulte a especificação própria do padrão.
Em nome da consistência entre os formatos, é necessário ter em mente o seguinte procedimento: ao desenvolver, por exemplo, um documento OpenAPI Json Schema (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 tipo equivalente no documento OpenAPIJson Schema, 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 Json Schema 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.
...
O exemplo a seguir mostra a modelagem da transação CostCenter, versão 2.000, usando o padrão OpenAPI (Swagger)Json Schema, considerando a obrigatoriedade da definição de InternalIds, mas não o seu uso. Ou seja, os campos de InternalId não são marcados como requeridos.
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 anteriormente. |
Bloco de código | ||
---|---|---|
| ||
{ "openapi$schema": "3.0.0", "info"https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/events/branch_2_001.json#", "info": { "description": "CentroContrato de Custo", Mensagem Padronizada para a entidade filial (Branch) para produtos TOTVS", "version": "2.000001", "title": "CostCenterBranch", "contact": { "name": " "name": "T-Talk" } }, "paths "url": {}, "servers": [ { "url"API.Totvs.com.br", "email": "http://api.totvscomiteintegracao@totvs.com.br/" } ], "components }, "x-totvs": { "transactionMessageDocumentation": { "schemas "subType": { "CostCenter"event", "businessContentType": { "type": "object", "required "$ref": [ "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": { "#/definitions/BranchType" }, "returnContentType": { "type": "object", "$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/ListOfInternalId_1_000.json#/definitions/ReturnContentWithModelType" } }, "messageDocumentation": { "name": "Branch", "description": "Filial", "segment": "FrameWork" }, "productInformation": { "protheus": { "contact": "[email protected]", "description": "Cadastro de Filial", "adapter": "apcfg230i.prw", "helpUrl": "link aqui" } } } }, "definitions": { "BranchType": { "type": "object", "properties": { "CompanyCode": { "type": "string", "example": "D", "description": "InternalIdCódigo da empresaEmpresa" }, "Code": { "type": "string", "description": "Código do centro de custo" }, "InternalId": { "type": "string", "description": "InternalId do centro de custo" }, "RegisterSituation": { , "x-totvs": { "protheus": { "Field": "XX8.XX8_CODIGO", "Required": false, "Type": "Char", "length": "12", "avialable": true, "canUpdate": false } } }, "Description": { "type": "string", "description "example": "IndicaFilial seSão o centro de custo está ativo ou não.", "enum": [ "Active", "Inactive" ] }, "Name": { "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}" } } } }Paulo 1", "description": "Descrição", "x-totvs": { "protheus": { "Field": "XX8.XX8_NOME", "Required": false, "Type": "Char", "length": "100", "avialable": true, "canUpdate": false } } }, "Code": { "type": "string", "example": "D SP 01", "description": "Filial/Codigo Unidade", "x-totvs": null } } } } } |