Questions tagged [swagger]
Swagger is a framework implementation for describing, producing, consuming, and visualizing RESTful web services, based on the OpenAPI specification
swagger
12,337
questions
290
votes
14
answers
198k
views
How to omit methods from Swagger documentation on WebAPI using Swashbuckle
I have a C# ASP.NET WebAPI application with API documentation being automatically generated using Swashbuckle. I want to be able to omit certain methods from the documentation but I can't seem to ...
- 3,830
218
votes
8
answers
268k
views
How to import Swagger APIs into Postman?
Recently I wrote restful APIs with SpringMvc and swagger-ui(v2). I noticed the Import function in Postman:
So my question is how to create the file which Postman needed?
I am not familiar with ...
- 2,610
179
votes
7
answers
321k
views
How to use 'Authorization: Bearer <token>' in a Swagger Spec
I am trying to convey that the authentication/security scheme requires setting a header as follows:
Authorization: Bearer <token>
This is what I have based on the swagger documentation:
...
- 2,158
172
votes
1
answer
168k
views
How to define a property that can be string or null in OpenAPI (Swagger)?
I have JSON schema file where one of the properties is defined as either string or null:
"type":["string", "null"]
When converted to YAML (for use with OpenAPI/Swagger), it becomes:
type:
- 'null'...
- 2,753
156
votes
5
answers
299k
views
What is the correct way to declare a date in an OpenAPI / Swagger-file?
What is the correct way to declare a date in a swagger-file object? I would think it is:
startDate:
type: string
description: Start date
example: "2017-01-01"
format: date
...
- 4,256
152
votes
16
answers
312k
views
How to send custom headers with requests in Swagger UI?
I have some endpoints in the API - /user/login, /products.
In Swagger UI I post email and password to /user/login and as a response I receive a token string.
Then, I can copy the token from the ...
- 52.5k
136
votes
36
answers
292k
views
Swashbuckle/Swagger + ASP.Net Core: "Failed to load API definition"
I develop an ASP.NET Core 2 application and included Swagger. Everything worked fine until I introduced a method without explicitly defining the HTTP action:
public class ErrorController : Controller
{...
- 3,413
135
votes
16
answers
285k
views
How to configure Spring Security to allow Swagger URL to be accessed without authentication
My project has Spring Security.
Main issue: Not able to access swagger URL at http://localhost:8080/api/v2/api-docs. It says Missing or invalid Authorization header.
Screenshot of the browser window
...
- 1,383
131
votes
10
answers
240k
views
How to export swagger.json (or yaml)
How can I export a Swagger definition file? It should be a JSON or YAML file, e.g. swagger.json or swagger.yaml.
Let's say I have an endpoint looking like http://example.com//swagger/ui/index#!:
The ...
- 77k
126
votes
13
answers
210k
views
Converting Swagger specification JSON to HTML documentation
For some REST APIs written in PHP, I was asked to create Swagger documentation, and since I was not aware of any easy way of annotating those existing APIs and create such a documentation, I used this ...
- 1,789
122
votes
13
answers
122k
views
Swagger/OpenAPI mock server
I have an API reference in a Swagger file. I want to create a very simple mock server, so that when I call e.g.:
mymockurl.com/users it will return a predefined JSON (no need to connect to a database)...
- 4,176
117
votes
9
answers
69k
views
swagger error: Conflicting schemaIds: Duplicate schemaIds detected for types A and B
Using Web API and using swashbuckle to generate swagger documentation,
I defined two different classes with the same name in two different namespaces. when I open swagger page in my browser it says
...
- 4,914
116
votes
3
answers
134k
views
How can I generate swagger based off of existing postman collection? [closed]
I am developing a REST API. during development I have used postman (chrome extension) to use and document my API. It is a wonderful tool and I have most of my API endpoints in it.
However, as we near ...
- 1,538
115
votes
39
answers
209k
views
ASP.NET Core - Swashbuckle not creating swagger.json file
I am having trouble getting the Swashbuckle.AspNetCore (1.0.0) package to generate any output. I read the swagger.json file should be written to '~/swagger/docs/v1'. However, I am not getting any ...
- 30.7k
109
votes
13
answers
318k
views
Swagger TypeError: Failed to execute 'fetch' on 'Window': Request with GET/HEAD method cannot have body
I have added Swagger to my Spring Boot 2 application:
This is my Swagger config:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
// @...
- 24.9k
105
votes
2
answers
66k
views
Swagger/OpenAPI - use $ref to pass a reusable defined parameter
Let's say I've got a parameter like limit. This one gets used all over the place and it's a pain to have to change it everywhere if I need to update it:
parameters:
- name: limit
in: query
...
- 70.8k
103
votes
4
answers
200k
views
How to specify if a field is optional or required in OpenAPI/Swagger?
How to I define in OpenAPI/Swagger if a field is optional or required and what is the default?
- 5,109
98
votes
22
answers
152k
views
How to configure Swashbuckle to ignore property on model
I'm using Swashbuckle to generate swagger documentation\UI for a webapi2 project. Our models are shared with some legacy interfaces so there are a couple of properties I want to ignore on the models. ...
- 7,628
95
votes
20
answers
219k
views
How to open local files in Swagger-UI
I'm trying to open my self generated swagger specification file my.json with swagger-ui on my local computer.
So I downloaded the latest tag v2.1.8-M1 and extracted the zip. Then I went inside the ...
- 1,463
95
votes
4
answers
118k
views
Swagger Inheritance and Composition
In my "simplified" API, all responses are derived (inherit) from a base "response" class. The response class is composed of a header filled with metadata, and the body which contains the core data the ...
- 12.4k
92
votes
6
answers
38k
views
swagger-ui returns 500 after deployment
Out of the box configuration works perfectly on my machine, no problems at all.
But when I deploy to our test environment - I get the following message
500 : { "Message": "An error has occurred." }...
- 4,968
92
votes
8
answers
118k
views
How to generate JSON-Schema from Swagger API Declaration
I have Swagger API Declaration for services using Swagger v 1.2.
My original feeling about Swagger was that it is very close to JSON Schema (Draft 3 and lately Draft 4) and it shall be relatively easy ...
- 43.4k
88
votes
2
answers
87k
views
How to annotate a field as deprecated in OpenAPI (Swagger) 2.0?
I have the following schema definition:
swagger: '2.0'
...
definitions:
Service:
type: object
properties:
serviceId:
type: string
description: Device or service ...
- 2,299
88
votes
12
answers
102k
views
Generate static docs with swagger
Is there a method for creating static documentation for swagger 2.0?
Perhaps like the 'preview' on editor.swagger.io.
I need to get static html files so I can include them in some static documents.
...
- 5,895
88
votes
2
answers
93k
views
Swagger; specify two responses with same code based on optional parameter
This question is not a duplicate of (Swagger - Specify Optional Object Property or Multiple Responses) because that OP was trying to return a 200 or a 400.
I have a GET with an optional parameter; e....
- 13.2k
87
votes
3
answers
101k
views
A 'simple' way to implement Swagger in a Spring MVC application
I have a ReSTFul API written in simple Spring (no Spring Boot, no fancy stuff!). I need to implement Swagger into this. So far, EVERY page on the internet has only driven me crazy with confusing ...
- 1,294
87
votes
5
answers
77k
views
Swagger 2.0 - how to make "one or the other" parameter required?
I have a swagger 2.0 resource defined below. How can I make "param1 or param2" required? Caller has to pass either param1 or param2.
/some/res:
put:
summary: some resource
responses:
200:
...
- 2,509
84
votes
4
answers
189k
views
How to define an enum in OpenAPI (Swagger)?
Does anyone know how to define possible enum values in an OpenAPI 2.0 definition so that they will be displayed in the Model tab of Swagger UI? Example here has an enum option for the status property. ...
- 1,184
83
votes
7
answers
48k
views
InvalidOperationException: Can't use schemaId .. The same schemaId is already used for type
I receive the following error.
InvalidOperationException: Can't use schemaId "$Registration" for type "$PortalService.Models.Registration". The same schemaId is already used for ...
- 1,363
83
votes
2
answers
101k
views
How to format Swagger 2.0 text descriptions?
I would like to format my Swagger API descriptions so that they are not simple paragraphs of text. Preferably, I'd like to add a small table to it.
I did not find an online reference about text ...
- 7,643
82
votes
8
answers
141k
views
How to change base url of Swagger in ASP.NET core
By default when you enable swagger in ASP.NET Core project it's available on url:
http://localhost:<random_port>/swagger/ui
I would like to use a different base url instead of /swagger/ui. How/...
- 31.2k
81
votes
4
answers
162k
views
How to post files in Swagger (OpenAPI)?
I am using Swagger to document my REST services. One of my services requires a CSV file to be uploaded. I added the following to the parameters section in my JSON API definition:
{
"name": "...
- 2,773
78
votes
12
answers
161k
views
Web Api How to add a Header parameter for all API in Swagger
I searched for possible ways to add a request header parameter that would be added automatically to every method in my web-api but i couldn't find a clear one.
While searching i found that the ...
user2245758
78
votes
7
answers
57k
views
Api annotation's description is deprecated
In Swagger, the @Api annotation's description element is deprecated.
Deprecated.
Not used in 1.5.X, kept for legacy support.
Is there a newer way of providing the description?
- 3,416
78
votes
7
answers
206k
views
How to describe a model in Swagger for an array with simple objects?
I have a REST services to document,
some of them accepts simple array like:
[
{ "name":"a" },
{ "name":"b" },
{ "name":"c" }
]
How do I describe this in Swagger model section ? I can only ...
- 2,797
74
votes
6
answers
131k
views
How to define an optional parameter in path using swagger
There is a function in my REST web service working with GET method and it has two optional parameters.
I tried to define it in Swagger but I encountered an error, Not a valid parameter definition, ...
- 1,316
72
votes
5
answers
86k
views
Validating JSON against Swagger API schema
I created an API spec from some JSON files and I am trying to test if the files validate against the API spec.
There are some good tools to validate against JSON Schema, but I did not have chance to ...
- 7,904
70
votes
9
answers
69k
views
swagger .net core API ambiguous HTTP method for Action Error
Implementing Swashbuckle/Swagger with .net Core 2 API I am now receiving the 500 error when accessing swagger.json:
NotSupportedException: Ambiguous HTTP method for action -
EBisAPI.Controllers....
- 2,816
68
votes
7
answers
66k
views
JWT Authentication and Swagger with .NET Core 3.0
I am developing some Web API with .NET Core 3.0 and want to integrate it with SwashBuckle.Swagger.
It is working fine, but when I add JWT authentication, it does not work as I expect.
To do that, I ...
68
votes
6
answers
64k
views
Why there are no themes for swagger-ui? [closed]
I like swagger for documenting Restful APIs very much, especially "Try it out!" button, but swagger-ui interface doesn't look very cool.
And I cannot believe there are no templates for such amazing ...
- 3,261
66
votes
8
answers
100k
views
Springfox 3.0.0 is not working with Spring Boot 2.6.0 [duplicate]
Springfox 3.0.0 is not working with Spring Boot 2.6.0, after upgrading I am getting the following error
org.springframework.context.ApplicationContextException: Failed to start bean '...
- 8,847
66
votes
1
answer
51k
views
What does 'required' in OpenAPI really mean
Given the following OpenAPI definition
Person:
required:
- id
type: object
properties:
id:
type: string
Which of the below objects are valid? Only A, or A & B?
A. {"id&...
- 23.1k
66
votes
4
answers
159k
views
How to escape colons and other special characters in a YAML string?
I have the following YAML fragment:
description: |
"API for bean consuming applications.
Examples: painted pony, lima bean"
Swagger editor interprets the colon (:) as a special character, ...
- 3,439
66
votes
9
answers
103k
views
How to generate basic TypeScript interfaces from Swagger schema?
I'm looking for a way to generate simplistic TypeScript interfaces from a Swagger schema. Most solutions I find are needlessly complicated.
I would like to generate interfaces like this:
export ...
- 4,008
64
votes
9
answers
74k
views
Actions require unique method/path combination for Swagger
I have 2 HTTP GET method in same controller and give me this error
HTTP method "GET" & path "api/DataStore" overloaded by actions - DPK.HostApi.Controllers.DataStoreController.GetByIdAsync (DPK....
user9390243
64
votes
6
answers
130k
views
Swagger Editor shows the "Schema error: should NOT have additional properties" error for a path parameter
I'm using http://editor.swagger.io to design an API and I get an error which I don't know how to address:
Schema error at paths['/employees/{employeeId}/roles'].get.parameters[0]
should NOT have ...
- 2,804
61
votes
7
answers
48k
views
Can Swagger autogenerate its yaml based on existing express routes?
I inherited an existing API and I would like to document it with swagger, but I don't yet know the full scope of it. Can Swagger (or another middleware/tool) auto-magically generate the yaml (for ...
- 4,125
60
votes
4
answers
120k
views
How to generate a Swagger #definition from sample JSON
Take the following #definition from the pet store example. Given a #definition section a JSON structure can be generated
e.g.
Is there something that can do the reverse given a largeish complex JSON ...
- 3,921
59
votes
1
answer
24k
views
What is Swagger, Swashbuckle and Swashbuckle UI
This is my understanding:
Swagger is a notation/rules to write documentation. But why is it called a framework (like Angular/MVC)?
Swashbuckle is a program (JavaScript?) that generates the ...
- 7,726
58
votes
1
answer
27k
views
What is Swagger and does it relate to OData?
I am familiar with the Microsoft stack. I am using OData for some of my restful services. Recently I came across Swagger for API documentation and I am trying to understand how it relates to OData. ...
- 9,139