Skip to content

[Bug] I keep getting "warning: Skip unsupported file swagger.json" and REST API docs aren't generated. #11064

@RomanGirin

Description

@RomanGirin

Describe the bug
I keep getting "warning: Skip unsupported file C:/Repos/API/WebAPI/swagger.json" and REST API docs aren't generated.

To Reproduce
Steps to reproduce the behavior (I give the smallest swagger.json file to reproduce the issue, in fact it describes sample one-method-API, but it still looks long - so sorry for that):

  1. Here is my swagger.json
{
	"openapi": "3.0.0",
	"info": {
		"title": "My Title",
		"version": "1.0.0"
	},
	"servers": [
		{
			"url": "http://localhost:9090"
		}
	],
	"paths": {
		"/api/agentsets/{agentsetID}/PrioritiesOfAgent": {
			"get": {
				"tags": [
					"AgentPriorities"
				],
				"summary": "Some demo API method related to some software agent.",
				"operationId": "AgentPriorities_GetAgentSetAgents",
				"parameters": [
					{
						"name": "agentsetID",
						"in": "path",
						"required": true,
						"description": "The unique identifier of the agent set whose agent priorities are being retrieved.",
						"schema": {
							"type": "string",
							"format": "guid"
						},
						"x-position": 1
					}
				],
				"responses": {
					"200": {
						"description": "Returns the list of agent priorities for the agent set.",
						"content": {
							"application/json": {
								"schema": {
									"type": "array",
									"items": {
										"$ref": "#/components/schemas/AgentPriorityDTO"
									}
								}
							}
						}
					},
					"400": {
						"description": "The X-SessionID header is missing or invalid, or the request parameters are invalid.",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/ProblemDetails"
								}
							}
						}
					},
					"500": {
						"description": "An unexpected server error occurred."
					}
				}
			},
			"options": {
				"tags": [
					"AgentPriorities"
				],
				"summary": "Returns the allowed HTTP methods for the agent priorities endpoint.",
				"operationId": "AgentPriorities_GetAgentPrioritiesOptions",
				"parameters": [
					{
						"name": "agentsetID",
						"in": "path",
						"required": true,
						"schema": {
							"type": "string"
						},
						"x-position": 1
					}
				],
				"responses": {
					"200": {
						"description": "Returns the allowed HTTP methods in the Allow header."
					}
				}
			}
		}
	},
	"components": {
		"schemas": {
			"AgentPriorityDTO": {
				"type": "object",
				"description": "Describes an agent.",
				"additionalProperties": false,
				"properties": {
					"agentID": {
						"type": "string",
						"description": "Unique identifier of the agent.",
						"format": "guid"
					},
					"agentSetID": {
						"type": "string",
						"description": "Unique identifier of the agent set.",
						"format": "guid"
					},
					"priority": {
						"type": "integer",
						"description": "Scheduling priority of the agent within the set.",
						"format": "int32"
					}
				}
			},
			"ProblemDetails": {
				"type": "object",
				"additionalProperties": {
					"nullable": true
				},
				"properties": {
					"type": {
						"type": "string",
						"nullable": true
					},
					"title": {
						"type": "string",
						"nullable": true
					},
					"status": {
						"type": "integer",
						"format": "int32",
						"nullable": true
					},
					"detail": {
						"type": "string",
						"nullable": true
					},
					"instance": {
						"type": "string",
						"nullable": true
					}
				}
			}
		}
	}
}
  1. here is my docfx.json
{
  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
  "metadata": [
    {
      "src": [
        {
          "src": "some path on my local machine",
          "files": [
			"/API/WebAPI/swagger.json"
          ]
        }
      ],
      "dest": "api"
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "**/*.{md,yml}"
        ],
        "exclude": [
          "_site/**"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "output": "_site",
    "template": [
      "default",
      "modern"
    ],
    "globalMetadata": {
      "_appName": "API",
      "_appTitle": "API",
      "_enableSearch": true,
      "pdf": true,
	  "pdfCoverPage": "cover.html"
    }
  }
}
  1. Execute command docfx docfx.json --serve

I keep getting "warning: Skip unsupported file C:/Repos/API/WebAPI/swagger.json" and API docs aren't generated.

Expected behavior
I expect the described in swagger.json file REST API method to appear in generated page on given URL ( http://localhost:8080), page opens just fine BTW, but contains no generated description.
If there is an error in swagger.json I expect docfx to describe WHY the file wasn't processed, not just a warning which gives no clue what to fix. Provided here swagger.json was verified in https://editor.swagger.io/ and contains no warnings or errors.

Context (please complete the following information):

  • OS: Windows
  • Docfx version: docfx --version
    2.78.5+fafdcd5ddacdb756bd5c4b84f2f07c18292e4821

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions