You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@submarine.apache.org by "Kevin Su (Jira)" <ji...@apache.org> on 2020/05/04 19:10:00 UTC
[jira] [Comment Edited] (SUBMARINE-481) Use Swagger to describe and
document submarine RESTful APIs
[ https://issues.apache.org/jira/browse/SUBMARINE-481?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17099266#comment-17099266 ]
Kevin Su edited comment on SUBMARINE-481 at 5/4/20, 7:09 PM:
-------------------------------------------------------------
Thanks [~wangda] [~sunilg] [~jiwq] [~tangzhankun] for the review.
{quote}One major doubt. swagger: "2.0" is used here.
# Did you generate the experiment.yaml spec from source code?
# Or is it freshly prepared from a spec definition?
If we are planning to move to swagger: "3.0", its better we generate a template and prepare spec from it. swag command which converts annotation into json spec wont work in swagger 3.0
As far as I see, there are no annotations in source code, so cud u pls confirm whether we are going 1) or 2) model ?
{quote}
The new experiment API definition that had not yet been implemented, I use Swagger editor to generate API definition by swagger 2.0.
swagger support [https://mermade.org.uk/openapi-converter] let us not take too much effort to migrate to swagger 3.0.
I also tried to add swagger annotations in the current API [PR-271|https://github.com/apache/submarine/pull/271], so after source code refactor, we could modify correspond annotation to generate experiment.yaml
Updated [experiment.yaml|https://app.swaggerhub.com/apis/pingsutw/Submarine/1.0.0] and doc, including
- Add script spec
- Add distributed TF spec
- Add distributed PyTorch spec
- made the pre-defined spec to flat key-value pairs like [predefined experiment-template-api|https://github.com/apache/submarine/blob/master/docs/design/experiment-implementation.md#predefined%20experiment-template-api-to-run-experiment]
- Add Resource spec instead of a string like "cpu=1,memory=1024M"
was (Author: pingsutw):
Thanks [~wangda] [~sunilg] [~jiwq] [~tangzhankun] for the review.
{quote}One major doubt. swagger: "2.0" is used here.
# Did you generate the experiment.yaml spec from source code?
# Or is it freshly prepared from a spec definition?
If we are planning to move to swagger: "3.0", its better we generate a template and prepare spec from it. swag command which converts annotation into json spec wont work in swagger 3.0
As far as I see, there are no annotations in source code, so cud u pls confirm whether we are going 1) or 2) model ?
{quote}
The new experiment API definition that had not yet been implemented, I use Swagger editor to generate API definition by swagger 2.0, but swagger support [https://mermade.org.uk/openapi-converter] let us not take too much effort to migrate to swagger 3.0.
I also tried to add swagger annotations in the current API [PR-271|https://github.com/apache/submarine/pull/271], so after source code refactor, we could modify correspond annotation to generate experiment.yaml
Updated [experiment.yaml|https://app.swaggerhub.com/apis/pingsutw/Submarine/1.0.0] and doc, including
- Add script spec
- Add distributed TF spec
- Add distributed PyTorch spec
- made the pre-defined spec to flat key-value pairs like [predefined experiment-template-api|https://github.com/apache/submarine/blob/master/docs/design/experiment-implementation.md#predefined%20experiment-template-api-to-run-experiment]
- Add Resource spec instead of a string like "cpu=1,memory=1024M"
> Use Swagger to describe and document submarine RESTful APIs
> -----------------------------------------------------------
>
> Key: SUBMARINE-481
> URL: https://issues.apache.org/jira/browse/SUBMARINE-481
> Project: Apache Submarine
> Issue Type: Improvement
> Components: Doc
> Reporter: Kevin Su
> Assignee: Kevin Su
> Priority: Major
> Labels: pull-request-available
> Attachments: experiment.yaml, swagger.yaml
>
>
> Follow [JobManagerRestApi.java|https://github.com/apache/submarine/blob/31f9322216307f958a1c3ec79e8a09cb0a5f5b5e/submarine-server/server-core/src/main/java/org/apache/submarine/server/rest/JobManagerRestApi.java#L44] and [Job.java |https://github.com/apache/submarine/blob/master/submarine-server/server-api/src/main/java/org/apache/submarine/server/api/job/Job.java], [submarine-server doc|https://github.com/apache/submarine/tree/master/docs/submarine-server] to define our job API by swagger
> We could copy swagger.ymal to [https://editor.swagger.io/] so that we could automatically generate doc and related client API.
> Anything I miss or something that needs to modify, please let me know
> cc [~leftnoteasy] [~liuxun] [~jiwq] [~tangzhankun]
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@submarine.apache.org
For additional commands, e-mail: dev-help@submarine.apache.org