Add API using Swagger file: parse json and yaml

[bajiat]

User story

As an API owner, I would like to be able to upload or link a Swagger file so that I can add an API to Catalog without manually entering the same data that can already be found from my Swagger file.

Goal

The goal of this task is to solve basic first steps for adding an API with reading data from Swagger file

• Get familiar with OpenAPI 2.0 specification and understand which fields in the Swagger document can be mapped to these APInf fields
  • Name
  • URL
  • Description
  • lifecycle status
• Find suitable open source NPM packages for
  • parsing YAML
  • parsing JSON
• Figure out how to validate, whether the file is valid Swagger file, valid json, valid yaml

Note: the actual UI implementation of Add API using Swagger to follow later.

[saransh-dev]

Hi @bajiat, I have following confusion:

1. On given example of swagger file, I am able to find the following things for add an api:- 1.1. Title 1.2. Description 1.3. Url

   But I am not getting the value of Lifecycle status . So from where I get the value of Lifecycle status ?

2. Do I need to validate the yaml or json file like i need to check wither values of info, host, schemes and paths are available or not ?

Please advise.

[Nazarah]

@saransh-dev Hi. The Lifecycle status is specific only to APInf platform. A Swagger file usually doesn't contain any lifecycle status for an API. Also from APInf's perspective, Life Cycle status is not mandatory for selection while adding an API. So can you please try and see that when an API is added using a swagger file, the variable "Lifecycle" has a null value? would that be a possible solution?

[saransh-dev]

@Nazarah We can do one thing more, when we are going to upload swagger file at that time we also provide a select field to set life cycle status of an api. Please advise.

[Nazarah]

@saransh-dev The option should be available. However, this shouldn't be mandatory as API owner can leave it out empty or can change it anytime after the API has been added.

[bajiat]

@saransh-dev

You should validate the file, because we need to know if it is valid json or yaml. The idea is to add the information to the fields, but also while adding the API also add the OpenAPI Designer file as documentation to that particular API. You do not need to create the UI for that yet, just find the most appropriate parsing options.

[bajiat]

Or actually it would be even better to validate if the file is actually a valid Swagger file. You should investigate what are the options to do this: services or packages that can validate Swagger.

[bajiat]

This is one potential option, but please explore: https://www.npmjs.com/package/swagger-express-validator

[Nazarah]

Consider this one as well @saransh-dev https://github.com/BigstickCarpet/swagger-parser

[marla-singer]

@Nazarah @saransh-dev The project already has the library to parse swagger file https://github.com/apinf/platform/blob/develop/package.json#L38

And the method about parsing exists as well https://github.com/apinf/platform/blob/914cddea9b0e4c0e67cd9f12a862ba3601020b3c/apinf_packages/api_docs/server/methods/swagger.js#L17-L19

cc:/ @preriasusi

[Nazarah]

@marla-singer we are good to go if the library can validate if the swagger or open api file is json or yaml, yml format.

[marla-singer]

if the swagger or open api file is json or yaml, yml format.

The function checks if the provided file is valid with OpenAPI specification. It does more that check if a file json or yaml. So yeah, it can be used in the current tesk

[marla-singer]

@Nazarah I'm wondering why this task doesn't have any wireframe for developer? :thinking: Becaus of this point?

Note: the actual UI implementation of Add API using Swagger to follow later.

[Nazarah]

I'll work on th the wireframe and make it available by tomorrow.

[marla-singer]

@Nazarah The task is in process and the developer has implemented some UI. Maybe it will helpful for you. This is "Add an API" page

[Nazarah]

@marla-singer are both view is going to be in the UI? Because I was thinking if we could have only 1 file uploader which could be used to upload either swagger or OpenAPI Specification. Please clarify.

[marla-singer]

The part with "Import API Configuration" doesn't relate to this task. It was done in the context of issue #2945 and it expects configuration as

{
  "name": "API name",
  "url": "http://url.com""
}

You can go to nightly.apinf.io and check "Add an API" page

The section with title "Import OpenAPI specification" relates to current task and expects the Swagger (OpenAPI is the new name of Swagger) document

[Nazarah]

@marla-singer Questions:

1. What is the purpose of the dropmenu before the file browser field? I am currently seeing the option "file" as selected. Are we able to select through the dropdown in what way we want to add an api? (e.g.manual add or add by file upload)

2. Would there be some notification when the parser checks the file to be of valid json, yaml or yml? What about the alert if attempts made to upload non-supported format?

3. Have you considered the option to provide the file via web URL or GitHub?