Share via

Unable to import Swagger JSON file

  • Article

Question

Friday, October 7, 2016 1:31 PM

I'm using Azure's API Management, and I am unable to import a JSON file for Swagger documentation of my API. I'm sure it's just a syntactical error, but I'm having trouble finding any resolution on the internet. The file is located at mailaletterapi.cloudapp.net/api/v2/api-docs.json. The error I'm getting is this:

One or more fields contain incorrect values:
Invalid value of the Web service URL
All template parameters used in the UriTemplate must be defined in the Operation, and vice-versa.
All template parameters used in the UriTemplate must be defined in the Operation, and vice-versa.

All replies (5)

Friday, October 7, 2016 5:54 PM | 1 vote

Hi Paul,

I'm currently investigating what the issue is.  We do support importing Swagger 1.2, but much more commonly, we see customers using Swagger 2.0 as there are much better tools available for validating and editing Swagger 2.0.  If you want any assistance converting it to 2.0, I'm happy to help.  In the meanwhile, I'll find out why your current document fails to import.

Regards,

Darrel

Darrel

Friday, October 7, 2016 6:27 PM | 1 vote

Hey Paul,

I believe I have found the issues.  The `basePath` property needs to be a valid URL.  So you need a http(s):// in front of what you currently have.  

For the /contacts/{id} operation, there was no `id` parameter defined. 

Also, for the /contacts path, the parameters are currently set to "path" but set to required = false.  Swagger does not allow this.  I changed those parameters to "query" and then the document is successful imported.

The updated Swagger is here:

{
  "apiVersion": "2.0",
  "swaggerVersion": "1.2",
  "basePath": "http://mailaletterapi.cloudapp.net/api/v2",
  "apis": [
    {
      "path": "/contacts",
      "operations": [
        {
          "summary": "Shows all contacts, with optional search parameters.",
          "parameters": [
            {
              "paramType": "query",
              "name": "name",
              "type": "string",
              "description": "Full name of the contact",
              "required": false
            },
            {
              "paramType": "query",
              "name": "company",
              "type": "string",
              "description": "Company name for the contact",
              "required": false
            },
            {
              "paramType": "query",
              "name": "address",
              "type": "string",
              "description": "Address for the contact",
              "required": false
            },
            {
              "paramType": "query",
              "name": "city",
              "type": "string",
              "description": "City for the contact",
              "reqruied": false
            },
            {
              "paramType": "query",
              "name": "state",
              "type": "string",
              "description": "State for the contact",
              "reqruied": false
            },
            {
              "paramType": "query",
              "name": "zip code",
              "type": "string",
              "description": "Five-digit zip code for the contact",
              "reqruied": false
            },
            {
              "paramType": "query",
              "name": "country",
              "type": "string",
              "description": "Country for the contact",
              "reqruied": false
            }
          ],
          "responseMessages": [
            {
              "code": 200,
              "message": "Success"
            },
            {
              "code": 401,
              "message": "Unauthorized"
            },
            {
              "code": 422,
              "message": "Unprocessable entity"
            }
          ],
          "method": "get",
          "nickname": "Contacts#index"
        },
        {
          "summary": "Creates a Contact",
          "parameters": [
            {
              "paramType": "form",
              "name": "title",
              "type": "string",
              "description": "Title for the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "first name",
              "type": "string",
              "description": "First name of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "last name",
              "type": "string",
              "description": "Last name of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "full name",
              "type": "string",
              "description": "Full name of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "company",
              "type": "string",
              "description": "Company of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "first address line",
              "type": "string",
              "description": "First address line of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "second address line",
              "type": "string",
              "description": "Seccond address line of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "third address line",
              "type": "string",
              "description": "Third address line of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "city",
              "type": "string",
              "description": "City of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "state",
              "type": "string",
              "description": "State of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "five digit zip code",
              "type": "string",
              "description": "Five-digit zip code of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "four digit zip code",
              "type": "string",
              "description": "Four-digit zip code of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "country",
              "type": "string",
              "description": "Country of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "email",
              "type": "string",
              "description": "Email of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "job title",
              "type": "string",
              "description": "Job title of the contact",
              "required": false
            }
          ],
          "responseMessages": [
            {
              "code": 201,
              "message": "Created"
            },
            {
              "code": 401,
              "message": "Unauthorized"
            },
            {
              "code": 422,
              "message": "Unprocessable entity"
            }
          ],
          "method": "post",
          "nickname": "Contacts#create"
        }
      ]
    },
    {
      "path": "/contacts/{id}",
      "operations": [
        {
          "summary": "Updates an existing Contact",
          "parameters": [
              {
              "paramType": "path",
              "name": "id",
              "type": "string",
              "description": "Id of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "title",
              "type": "string",
              "description": "Title for the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "first name",
              "type": "string",
              "description": "First name of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "last name",
              "type": "string",
              "description": "Last name of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "full name",
              "type": "string",
              "description": "Full name of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "company",
              "type": "string",
              "description": "Company of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "first address line",
              "type": "string",
              "description": "First address line of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "second address line",
              "type": "string",
              "description": "Seccond address line of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "third address line",
              "type": "string",
              "description": "Third address line of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "city",
              "type": "string",
              "description": "City of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "state",
              "type": "string",
              "description": "State of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "five digit zip code",
              "type": "string",
              "description": "Five-digit zip code of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "four digit zip code",
              "type": "string",
              "description": "Four-digit zip code of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "country",
              "type": "string",
              "description": "Country of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "email",
              "type": "string",
              "description": "Email of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "job title",
              "type": "string",
              "description": "Job title of the contact",
              "required": false
            }
          ],
          "responseMessages": [
            {
              "code": 200,
              "message": "Success"
            },
            {
              "code": 401,
              "message": "Unauthorized"
            },
            {
                "code": 404,
                "message": "Not Found"
            },
            {
                "code": 422,
                "message": "Unprocessable entity"
            }
          ],
          "method": "patch",
          "nickname": "Contacts#update"
        }
      ]
    }
  ],
  "authorizations": null,
  "info": {
    "title": "MailALetter API",
    "description": "Utilize REST architecture to print your letters.",
    "contact": "classicjazz@gmail.com"
  }
}

Darrel

Friday, October 7, 2016 6:32 PM

Hey Paul,

I believe I have found the issues.  The `basePath` property needs to be a valid URL.  So you need a http(s):// in front of what you currently have.  

For the /contacts/{id} operation, there was no `id` parameter defined. 

Also, for the /contacts path, the parameters are currently set to "path" but set to required = false.  Swagger does not allow this.  I changed those parameters to "query" and then the document is successful imported.

The updated Swagger is here:

{
  "apiVersion": "2.0",
  "swaggerVersion": "1.2",
  "basePath": "http://mailaletterapi.cloudapp.net/api/v2",
  "apis": [
    {
      "path": "/contacts",
      "operations": [
        {
          "summary": "Shows all contacts, with optional search parameters.",
          "parameters": [
            {
              "paramType": "query",
              "name": "name",
              "type": "string",
              "description": "Full name of the contact",
              "required": false
            },
            {
              "paramType": "query",
              "name": "company",
              "type": "string",
              "description": "Company name for the contact",
              "required": false
            },
            {
              "paramType": "query",
              "name": "address",
              "type": "string",
              "description": "Address for the contact",
              "required": false
            },
            {
              "paramType": "query",
              "name": "city",
              "type": "string",
              "description": "City for the contact",
              "reqruied": false
            },
            {
              "paramType": "query",
              "name": "state",
              "type": "string",
              "description": "State for the contact",
              "reqruied": false
            },
            {
              "paramType": "query",
              "name": "zip code",
              "type": "string",
              "description": "Five-digit zip code for the contact",
              "reqruied": false
            },
            {
              "paramType": "query",
              "name": "country",
              "type": "string",
              "description": "Country for the contact",
              "reqruied": false
            }
          ],
          "responseMessages": [
            {
              "code": 200,
              "message": "Success"
            },
            {
              "code": 401,
              "message": "Unauthorized"
            },
            {
              "code": 422,
              "message": "Unprocessable entity"
            }
          ],
          "method": "get",
          "nickname": "Contacts#index"
        },
        {
          "summary": "Creates a Contact",
          "parameters": [
            {
              "paramType": "form",
              "name": "title",
              "type": "string",
              "description": "Title for the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "first name",
              "type": "string",
              "description": "First name of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "last name",
              "type": "string",
              "description": "Last name of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "full name",
              "type": "string",
              "description": "Full name of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "company",
              "type": "string",
              "description": "Company of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "first address line",
              "type": "string",
              "description": "First address line of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "second address line",
              "type": "string",
              "description": "Seccond address line of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "third address line",
              "type": "string",
              "description": "Third address line of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "city",
              "type": "string",
              "description": "City of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "state",
              "type": "string",
              "description": "State of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "five digit zip code",
              "type": "string",
              "description": "Five-digit zip code of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "four digit zip code",
              "type": "string",
              "description": "Four-digit zip code of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "country",
              "type": "string",
              "description": "Country of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "email",
              "type": "string",
              "description": "Email of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "job title",
              "type": "string",
              "description": "Job title of the contact",
              "required": false
            }
          ],
          "responseMessages": [
            {
              "code": 201,
              "message": "Created"
            },
            {
              "code": 401,
              "message": "Unauthorized"
            },
            {
              "code": 422,
              "message": "Unprocessable entity"
            }
          ],
          "method": "post",
          "nickname": "Contacts#create"
        }
      ]
    },
    {
      "path": "/contacts/{id}",
      "operations": [
        {
          "summary": "Updates an existing Contact",
          "parameters": [
              {
              "paramType": "path",
              "name": "id",
              "type": "string",
              "description": "Id of the contact",
              "required": true
            },
            {
              "paramType": "form",
              "name": "title",
              "type": "string",
              "description": "Title for the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "first name",
              "type": "string",
              "description": "First name of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "last name",
              "type": "string",
              "description": "Last name of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "full name",
              "type": "string",
              "description": "Full name of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "company",
              "type": "string",
              "description": "Company of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "first address line",
              "type": "string",
              "description": "First address line of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "second address line",
              "type": "string",
              "description": "Seccond address line of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "third address line",
              "type": "string",
              "description": "Third address line of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "city",
              "type": "string",
              "description": "City of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "state",
              "type": "string",
              "description": "State of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "five digit zip code",
              "type": "string",
              "description": "Five-digit zip code of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "four digit zip code",
              "type": "string",
              "description": "Four-digit zip code of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "country",
              "type": "string",
              "description": "Country of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "email",
              "type": "string",
              "description": "Email of the contact",
              "required": false
            },
            {
              "paramType": "form",
              "name": "job title",
              "type": "string",
              "description": "Job title of the contact",
              "required": false
            }
          ],
          "responseMessages": [
            {
              "code": 200,
              "message": "Success"
            },
            {
              "code": 401,
              "message": "Unauthorized"
            },
            {
                "code": 404,
                "message": "Not Found"
            },
            {
                "code": 422,
                "message": "Unprocessable entity"
            }
          ],
          "method": "patch",
          "nickname": "Contacts#update"
        }
      ]
    }
  ],
  "authorizations": null,
  "info": {
    "title": "MailALetter API",
    "description": "Utilize REST architecture to print your letters.",
    "contact": "classicjazz@gmail.com"
  }
}

Darrel

Saturday, October 8, 2016 2:49 PM

I would love some assistance converting to 2.0, I've tried two different gems that are supposed to generate Swagger docs by adding a little configuration to the controllers, but neither of them has actually successfully created the json files, so I've done it all by hand. In addition to being tedious, I'm just not sure that I'm following the proper syntax.

Saturday, October 8, 2016 2:49 PM

Thank you very much, I'll plug this in to my code and see how it works!