kubeflow
/
pipelines
mirror of https://github.com/kubeflow/pipelines.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update API references and readme. Closes #8723 (#8828) 

* Update API references and readme. Closes #8723

* Add a note about html headers

* Remove folders, update readme
This commit is contained in:
gkcalat 2023-02-09 15:41:01 -08:00 committed by GitHub
parent 5e2475ef19
commit c8165859bd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 29 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
backend/api/README.md
View File

@ -46,12 +46,36 @@ Python client will be placed into `./${API_VERSION}/python_http_client`.
> **Note**
> Whenever the API definition changes (i.e., the file `kfp_api_single_file.swagger.json` changes), the API reference documentation needs to be updated.
API definitions in this folder are used to generate [the `v1beta1` API reference documentation on kubeflow.org](https://www.kubeflow.org/docs/components/pipelines/v1/reference/api/kubeflow-pipeline-api-spec/). `v2beta1` references are yet to be created on [kubeflow.org](https://www.kubeflow.org/docs/components/pipelines/v2/reference/). Follow the steps below to update the documentation:
API definitions in this folder are used to generate [`v1beta1`](https://www.kubeflow.org/docs/components/pipelines/v1/reference/api/kubeflow-pipeline-api-spec/) and [`v2beta1`](https://www.kubeflow.org/docs/components/pipelines/v2/reference/api/kubeflow-pipeline-api-spec/) API reference documentation on kubeflow.org. Follow the steps below to update the documentation:
1. Use [bootprint-openapi](https://github.com/bootprint/bootprint-monorepo/tree/master/packages/bootprint-openapi) and [html-inline](https://github.com/substack/html-inline) to generate the API reference documentation from `./${API_VERSION}/swagger/kfp_api_single_file.swagger.json`. [These instructions](https://github.com/bootprint/bootprint-monorepo/tree/master/packages/bootprint-openapi#bootprint-openapi) show how to generate *a single self-contained html file* with API reference documentation from a json file.
2. For `v1beta1`, use the above generated html to replace the relevant section (which is below the title section) in file [kubeflow-pipeline-api-spec.html](https://github.com/kubeflow/website/blob/master/content/en/docs/components/pipelines/v1/reference/api/kubeflow-pipeline-api-spec.html).
3. Similarly, `v2beta1` API reference documentation needs to be placed into the [corresponding folder](https://github.com/kubeflow/website/tree/master/content/en/docs/components/pipelines/v2) and added to the [reference.md](https://github.com/kubeflow/website/blob/master/content/en/docs/components/pipelines/v2/reference.md)
4. Create a PR with the changes in [kubeflow.org website repository](https://github.com/kubeflow/website).
1. Install [bootprint-openapi](https://github.com/bootprint/bootprint-monorepo/tree/master/packages/bootprint-openapi) and [html-inline](https://www.npmjs.com/package/html-inline) packages using `npm`:
```bash
npm install -g bootprint
npm install -g bootprint-openapi
npm -g install html-inline
```
2. Generate *self-contained html file(s)* with API reference documentation from `./${API_VERSION}/swagger/kfp_api_single_file.swagger.json`:
Fov `v1beta1`:
```bash
bootprint openapi ./v1beta1/swagger/kfp_api_single_file.swagger.json ./temp/v1
html-inline ./temp/v1/index.html > ./temp/v1/kubeflow-pipeline-api-spec.html
```
For `v2beta1`:
```bash
bootprint openapi ./v2beta1/swagger/kfp_api_single_file.swagger.json ./temp/v2
html-inline ./temp/v2/index.html > ./temp/v2/kubeflow-pipeline-api-spec.html
```
3. Use the above generated html file(s) to replace the relevant section(s) on kubeflow.org. When copying th content, make sure to **preserve the original headers**.
- `v1beta1`: file [kubeflow-pipeline-api-spec.html](https://github.com/kubeflow/website/blob/master/content/en/docs/components/pipelines/v1/reference/api/kubeflow-pipeline-api-spec.html).
- `v2beta1`: file [kubeflow-pipeline-api-spec.html](https://github.com/kubeflow/website/blob/master/content/en/docs/components/pipelines/v2/reference/api/kubeflow-pipeline-api-spec.html).
4. Create a PR with the changes in [kubeflow.org website repository](https://github.com/kubeflow/website). See an example [here](https://github.com/kubeflow/website/pull/3444).
## Updating API generator image