Stack Overflow
Stack Overflow

Questions tagged [swagger]

Swagger is a framework implementation for describing, producing, consuming, and visualizing RESTful web services, based on the OpenAPI specification

Swagger is a specification and framework implementation for describing, producing, consuming and visualizing RESTful web services. It is a unique way to document your RESTful APIs on the go, as and when you code them.

The main advantage of Swagger is its flexibility - it can produce static and dynamic REST API documentation. There is even the possibility to interact with the webservice and send example queries.

It's developed by SmartBear.

On Nov 5th, 2015, the Open API Initiative extended Swagger as an OpenAPI specification to advance connected application development through open standards. Please refer to the announcement for more information.

Useful links

Frequently Asked Questions

People often ask about the following Swagger topics:

Related tags

11997 questions
99
votes
2 answers

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 description: Limits the number of returned…
brandonscript
  • 68,675
  • 32
  • 163
  • 220
96
votes
3 answers

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?
user79074
  • 4,937
  • 5
  • 29
  • 57
95
votes
21 answers

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. I can't use JsonIgnore attribute because the…
mutex
  • 7,536
  • 8
  • 45
  • 66
93
votes
4 answers

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 the user is requesting. The response (in JSON)…
Programster
  • 12,242
  • 9
  • 49
  • 55
91
votes
6 answers

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." } /api/swagger/docs/v1 The deployment is to…
VisualBean
  • 4,908
  • 2
  • 28
  • 57
90
votes
19 answers

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 sub folder dist and copied the file my.json into it.…
Adam Taras
  • 1,403
  • 1
  • 13
  • 15
88
votes
8 answers

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 to generate JSON Schema for request and response…
Jan Vlcinsky
  • 42,725
  • 12
  • 101
  • 98
86
votes
3 answers

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 configurations and bloated code that I did not find…
wavicle
  • 1,284
  • 1
  • 10
  • 12
86
votes
12 answers

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. So far I've not found a way to do this. I see there…
romeovs
  • 5,785
  • 9
  • 43
  • 74
84
votes
5 answers

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: description: Successful response schema: …
Vineet Bhatia
  • 2,469
  • 4
  • 30
  • 28
81
votes
2 answers

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 formatting in Swagger descriptions. If I launch the…
TERACytE
  • 7,553
  • 13
  • 75
  • 111
80
votes
2 answers

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 identification number example: 1111111111 …
saeedj
  • 2,179
  • 9
  • 25
  • 38
80
votes
4 answers

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. How to do define such an enum in OpenAPI 2.0?
eloleon
  • 1,144
  • 2
  • 10
  • 18
78
votes
7 answers

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?
Soumitri Pattnaik
  • 3,246
  • 4
  • 24
  • 42
78
votes
2 answers

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.g., GET /endpoint?selector=foo. I want to return…
Tommy
  • 12,588
  • 14
  • 59
  • 110
1
2
3
…
99 100