Criando um arquivo de definição do Produto

Defina um Produto criando um arquivo de definição do Produto.

Sobre esta tarefa

É possível criar um arquivo de definição de Produto em uma das maneiras a seguir:
  • Crie o arquivo em um editor de sua preferência.
  • Crie uma arquivo de definição do Produto usando o comando apic create:product e, em seguida, modifique-o. É possível basear seu arquivo de definição de Produto no modelo de Produto padrão ou em seu próprio modelo customizado.
Este tópico descreve a sintaxe necessária para ambas as opções e também a estrutura necessária quando o arquivo é criado no editor. Para obter detalhes sobre o que você pode incluir no arquivo de definição de produto, consulte Esquema de definição de produto...
É possível criar um Produto na CLI executando apic create:product e fornecendo argumentos adicionais na linha de comandos. Por exemplo, é possível inserir o texto a seguir em um único comando:
apic create:product --name product_name --title product_title --filename product_file_name.yaml
--apis "filename_of_api1.yaml filename_of_api2.yaml"
em que:
  • product_name é o nome para seu novo Produto.
  • product_title é o título de seu novo Produto.
  • product_file_name.yaml é o nome do arquivo yaml criado para seu novo Produto.
  • filename_of_api1.yaml é o nome do arquivo de uma das APIs usadas dentro do novo Produto.
  • filename_of_api2.yaml é o nome do arquivo de uma das APIs usadas dentro do novo Produto.
Outra opção é criar um Produto interativamente na linha de comando executando apic create:product e seguindo os avisos.
É possível ver detalhes adicionais e opções disponíveis para o comando apic create:product inserindo o comando:
apic create:product --help
Também é possível criar um Produto a partir de um modelo customizado de Barras de direção usando o comando a seguir:
apic create:product --template template_filename --title product_title
em que template_filename é o nome do modelo de Barras de direção a ser usado e product_title é o título de seu Produto. Um arquivo de modelo de Produto deve ter uma extensão do nome do arquivo .hbs. É possível criar um modelo do zero ou iniciar com o modelo de Produto de exemplo (padrão) fornecido em Exemplos de modelo de definição de API e Produto.

Um arquivo de definição do Produto contém as seções a seguir:

  • A versão de especificação
  • Uma seção de informações
  • Uma seção de visibilidade
  • Uma seção APIs
  • Uma seção Planos

Neste tópico, usa-se YAML, mas as instruções podem ser adaptadas para usar JSON. Ambas as extensões de arquivo .yaml e .yml são suportadas, mas o uso da extensão do arquivo .yaml é recomendado pelo yaml.org

Nota: Todas as chaves e valores de enumeração especificados neste tópico fazem distinção entre maiúsculas e minúsculas.

Procedimento

Estruture seu arquivo de definição de Produto concluindo as etapas a seguir:

  1. Configure a versão de especificação incluindo a linha a seguir no início do arquivo: product: 1.0.0.
    Essa linha especifica a versão do modelo e sempre é product: 1.0.0.
    Nota: a versão da especificação é diferente da sua versão do Produto. A versão de especificação refere-se a este arquivo YAML, enquanto a versão do Produto é a seu critério.
  2. Inclua uma seção de informações com detalhes sobre o produto, conforme descrito em Concluindo a seção de informações da descrição do produto.
  3. Inclua uma seção de visibilidade que especifique quem pode visualizar e assinar o Produto, conforme descrito em Especificando a visibilidade de seu produto.
  4. Inclua uma seção de APIs que referencie as APIs a serem incluídas no Produto, conforme descrito em Referenciando as APIs para seu produto.
  5. Incluir uma seção Planos que descreveu os Planos que você deseja incluir em seu Produto, conforme descrito em Descrevendo Planos em seu produto.

Resultados

Você concluiu uma representação YAML de seu Produto. Um exemplo completo com indentação completa pode ser localizado em Uma representação YAML de exemplo de um Produto.

É possível criar a documentação multilíngue da API e do Produto usando uma extensão x-ibm-languages diretamente na definição OpenAPI . Para obter mais informações, consulte Usando x-ibm-languages para criar API multilíngue e documentação do produto.