JIRA API Gem 技术文档

1. 安装指南

1.1 安装 jira-ruby Gem

在开始使用 JIRA API Gem 之前，您需要先安装 jira-ruby Gem。可以通过以下命令进行安装：

gem install jira-ruby

1.2 生成公钥证书

在运行测试之前，您需要生成一个公钥证书。可以通过以下命令生成：

rake jira:generate_public_cert

1.3 设置 JIRA SDK（Mac OS）

如果您在 Mac OS 上运行测试，需要先安装 Atlassian SDK。按照以下步骤进行安装：

1. 访问 Atlassian SDK 安装指南，按照“Mac OSX Installer”部分的说明进行安装。
2. 安装完成后，进入 SDK 的安装目录，运行以下命令启动 JIRA：

./bin/atlas-run-standalone --product jira

启动后，您可以通过 http://localhost:2990/ 访问 JIRA 管理界面，使用 admin:admin 登录。

2. 项目的使用说明

2.1 连接到 JIRA

首先，您需要配置连接参数以连接到 JIRA 实例。以下是一个示例配置：

options = {
  :private_key_file => "rsakey.pem",
  :context_path     => '',
  :consumer_key     => 'your_consumer_key',
  :site             => 'your_jira_instance_url'
}

client = JIRA::Client.new(options)

2.2 获取并显示项目

连接成功后，您可以获取所有项目并显示它们的键和名称：

projects = client.Project.all

projects.each do |project|
  puts "Project -> key: #{project.key}, name: #{project.name}"
end

2.3 使用字段名称

jira-ruby Gem 允许您通过自定义字段名称引用字段，而不是使用标识符。在使用之前，请确保映射字段：

client.Field.map_fields

old_way = issue.customfield_12345

# 注意：映射的方法采用 PascalCase 和 snake_case 结合的命名风格
new_way = issue.Special_Field

2.4 使用 JQL 查询

您可以使用 JIRA Query Language (JQL) 根据特定条件查找问题：

client.Issue.jql(a_normal_jql_search, fields:[:description, :summary, :Special_field, :created])

2.5 创建、更新、删除问题

创建问题

issue = client.Issue.build
labels = ['label1', 'label2']
issue.save({
  "fields" => {
    "summary" => "blarg from in example.rb",
    "project" => {"key" => "SAMPLEPROJECT"},
    "issuetype" => {"id" => "3"},
    "labels" => labels,
    "priority" => {"id" => "1"}
  }
})

更新/转换问题

issue = client.Issue.find("10002")
issue.save({"fields"=>{"summary"=>"EVEN MOOOOOOARRR NINJAAAA!"}})

issue_transition = issue.transitions.build
issue_transition.save!('transition' => {'id' => transition_id})

删除问题

issue = client.Issue.find('SAMPLEPROJECT-2')
issue.delete

3. 项目 API 使用文档

3.1 搜索用户

您可以使用以下代码搜索用户：

users = client.User.search('username')
users.each do |user|
  puts "User -> name: #{user.name}, email: #{user.emailAddress}"
end

3.2 获取问题的观察者

您可以通过以下代码获取问题的观察者：

issue = client.Issue.find('SAMPLEPROJECT-1')
watchers = issue.watchers
watchers.each do |watcher|
  puts "Watcher -> name: #{watcher.name}"
end

3.3 更改问题的分配者

您可以通过以下代码更改问题的分配者：

issue = client.Issue.find('SAMPLEPROJECT-1')
issue.save({"fields"=>{"assignee"=>{"name"=>"new_assignee"}}})

3.4 添加附件和评论

您可以通过以下代码向问题添加附件和评论：

issue = client.Issue.find('SAMPLEPROJECT-1')
issue.attachments.build.save!('file' => '/path/to/file')
issue.comments.build.save!('body' => 'This is a comment')

4. 项目安装方式

4.1 使用 OAuth 配置 JIRA

1. 在 JIRA 中注册一个新的消费者。通过 JIRA 的“应用程序链接”管理界面创建新的应用程序链接。
2. 在创建应用程序链接时，使用占位符 URL 或客户端 URL（例如 http://localhost:3000），并选择“通用应用程序”类型。
3. 创建完成后，编辑配置并进入“传入身份验证”配置界面，选择 OAuth，并输入公钥和消费者密钥。

4.2 使用 HTTP Basic Auth 配置 JIRA

1. 按照上述步骤在 JIRA 中设置新的应用程序链接。
2. 无需设置“传入身份验证”，默认使用 HTTP Basic Auth。

4.3 使用 Cookie-Based Auth 配置 JIRA

1. 设置 :auth_type 为 :cookie，并启用 :use_cookies。
2. 设置 :username 和 :password。

options = {
  :username           => 'username',
  :password           => 'pass1234',
  :site               => 'http://mydomain.atlassian.net:443/',
  :context_path       => '',
  :auth_type          => :cookie,
  :use_cookies        => true
}

client = JIRA::Client.new(options)

4.4 使用 Personal Access Tokens Auth 配置 JIRA

1. 如果您的 JIRA 系统支持 Personal Access Token 授权，您需要设置 :default_headers 包含 API Token。

options = {
  :site               => 'http://mydomain.atlassian.net:443/',
  :context_path       => '',
  :default_headers    => { 'Authorization' => "Bearer #{api_token}" },
  :auth_type          => :basic
}

client = JIRA::Client.new(options)

通过以上步骤，您可以成功安装、配置并使用 JIRA API Gem 进行 JIRA 系统的操作。