Add doc for API

backend/api/experiment.proto

@@ -85,16 +85,19 @@ service ExperimentService {
 }
 
 message CreateExperimentRequest {
+  // The experiment to be created
   Experiment experiment = 1;
 }
 
 message GetExperimentRequest {
+  // The ID of the experiment to be retrieved
   string id = 1;
 }
 
 message ListExperimentsRequest {
   string page_token = 1;
   int32 page_size = 2;
+
   // Can be format of "field_name", "field_name asc" or "field_name des"
   // Ascending by default.
   string sort_by = 3;
@@ -105,12 +108,18 @@ message ListExperimentsRequest {
 }
 
 message ListExperimentsResponse {
+  // A list of experiments returned.
   repeated Experiment experiments = 1;
+
+  // The total number of experiments for the given query.
   int32 total_size = 3;
+
+  // The token to list the next page of experiments.
   string next_page_token = 2;
 }
 
 message DeleteExperimentRequest{
+  // The ID of the experiment to be deleted.
   string id = 1;
 }
 

backend/api/generate_api.sh

@@ -18,9 +18,12 @@
 # directory using Bazel, then copies them back into the source tree so they can
 # be checked-in.
 
+set -ex
+
 BAZEL_BINDIR=$(bazel info bazel-bin)
-SWAGGER_CMD=../../bazel-bin/external/com_github_go_swagger/cmd/swagger/*stripped/swagger
-AUTOGEN_CMD="../../bazel-bin/external/com_github_mbrukman_autogen/autogen_tool"
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" > /dev/null && pwd)"
+SWAGGER_CMD=${DIR}/../../bazel-bin/external/com_github_go_swagger/cmd/swagger/*stripped/swagger
+AUTOGEN_CMD="${DIR}/../../bazel-bin/external/com_github_mbrukman_autogen/autogen_tool"
 GENERATED_GO_PROTO_FILES="${BAZEL_BINDIR}/backend/api/api_generated_go_sources/src/github.com/kubeflow/pipelines/backend/api/go_client/*.go"
 
 # TODO this script should be able to be run from anywhere, not just within .../backend/api/
@@ -39,7 +42,7 @@ bazel build //backend/api:api_generated_go_sources
 set -x
 # Copy the generated files into the source tree and add license.
 for f in $GENERATED_GO_PROTO_FILES; do
-  target=go_client/$(basename ${f})
+  target=${DIR}/go_client/$(basename ${f})
   cp $f $target
   chmod 766 $target
   ${AUTOGEN_CMD} -i --no-tlc -c "Google LLC" -l apache $target
@@ -49,41 +52,47 @@ done
 bazel build //backend/api:api_swagger
 cp ${BAZEL_BINDIR}/backend/api/*.swagger.json swagger
 
+jq -s '
+    reduce .[] as $item ({}; . * $item) |
+    .info.title = "KF Pipelines API" |
+    .info.description = "Generated Kubeflow Pipelines server API"
+' ${DIR}/swagger/{run,job,pipeline,experiment,pipeline.upload}.swagger.json > "${DIR}/swagger/kfp_api_single_file.swagger.json"
+
 # Generate Go HTTP client from the swagger files.
 ${SWAGGER_CMD} generate client \
-  -f swagger/job.swagger.json \
+  -f ${DIR}/swagger/job.swagger.json \
   -A job \
   --principal models.Principal \
   -c job_client \
   -m job_model \
   -t go_http_client
 
 ${SWAGGER_CMD} generate client \
-  -f swagger/run.swagger.json \
+  -f ${DIR}/swagger/run.swagger.json \
   -A run \
   --principal models.Principal \
   -c run_client \
   -m run_model \
   -t go_http_client
 
 ${SWAGGER_CMD} generate client \
-  -f swagger/experiment.swagger.json \
+  -f ${DIR}/swagger/experiment.swagger.json \
   -A experiment \
   --principal models.Principal \
   -c experiment_client \
   -m experiment_model \
   -t go_http_client
 
 ${SWAGGER_CMD} generate client \
-  -f swagger/pipeline.upload.swagger.json \
+  -f ${DIR}/swagger/pipeline.upload.swagger.json \
   -A pipeline_upload \
   --principal models.Principal \
   -c pipeline_upload_client \
   -m pipeline_upload_model \
   -t go_http_client
 
 ${SWAGGER_CMD} generate client \
-  -f swagger/pipeline.swagger.json \
+  -f ${DIR}/swagger/pipeline.swagger.json \
   -A pipeline \
   --principal models.Principal \
   -c pipeline_client \
@@ -92,16 +101,16 @@ ${SWAGGER_CMD} generate client \
 
 # Hack to fix an issue with go-swagger
 # See https://github.com/go-swagger/go-swagger/issues/1381 for details.
-sed -i -- 's/MaxConcurrency int64 `json:"max_concurrency,omitempty"`/MaxConcurrency int64 `json:"max_concurrency,omitempty,string"`/g' ./go_http_client/job_model/api_job.go
-sed -i -- 's/IntervalSecond int64 `json:"interval_second,omitempty"`/IntervalSecond int64 `json:"interval_second,omitempty,string"`/g' ./go_http_client/job_model/api_periodic_schedule.go
-sed -i -- 's/MaxConcurrency string `json:"max_concurrency,omitempty"`/MaxConcurrency int64 `json:"max_concurrency,omitempty,string"`/g' ./go_http_client/job_model/api_job.go
-sed -i -- 's/IntervalSecond string `json:"interval_second,omitempty"`/IntervalSecond int64 `json:"interval_second,omitempty,string"`/g' ./go_http_client/job_model/api_periodic_schedule.go
+sed -i -- 's/MaxConcurrency int64 `json:"max_concurrency,omitempty"`/MaxConcurrency int64 `json:"max_concurrency,omitempty,string"`/g' ${DIR}/go_http_client/job_model/api_job.go
+sed -i -- 's/IntervalSecond int64 `json:"interval_second,omitempty"`/IntervalSecond int64 `json:"interval_second,omitempty,string"`/g' ${DIR}/go_http_client/job_model/api_periodic_schedule.go
+sed -i -- 's/MaxConcurrency string `json:"max_concurrency,omitempty"`/MaxConcurrency int64 `json:"max_concurrency,omitempty,string"`/g' ${DIR}/go_http_client/job_model/api_job.go
+sed -i -- 's/IntervalSecond string `json:"interval_second,omitempty"`/IntervalSecond int64 `json:"interval_second,omitempty,string"`/g' ${DIR}/go_http_client/job_model/api_periodic_schedule.go
 
 # Executes the //go:generate directives in the generated code.
 go generate ./...
 
 # Add license to files in go_http_client.
-find go_http_client/ -name "*.go" -exec ${AUTOGEN_CMD} -i --no-tlc -c "Google LLC" -l apache {} \;
+find ${DIR}/go_http_client/ -name "*.go" -exec ${AUTOGEN_CMD} -i --no-tlc -c "Google LLC" -l apache {} \;
 
 # Finally, run gazelle to add BUILD files for the generated code.
 bazel run //:gazelle