I have a C# ASP.NET WebAPI application with API documentation being automatically generated using [**Swashbuckle**][1].  I want to be able to **omit certain methods** from the documentation but I can&#39;t seem to work out how to tell Swagger not to include them in the Swagger UI output.  

I sense it is something to do with **adding a model or schema filter** but it isn&#39;t obvious what to do and the documentation only seems to provide examples of how to modify the output for a method, not remove it completely from the output.



  [1]: https://github.com/domaindrivendev/Swashbuckle

How to omit methods from Swagger documentation on WebAPI using Swashbuckle

Recently I wrote restful APIs with *SpringMvc* and swagger-ui(v2). I noticed the Import function in Postman:
 
[![enter image description here][1]][1]

So my question is how to create the file which Postman needed?

I am not familiar with Swagger.

  [1]: http://i.stack.imgur.com/d2ss7.png

How to import Swagger APIs into Postman?

I am trying to convey that the authentication/security scheme requires setting a header as follows:

    Authorization: Bearer &lt;token&gt;

This is what I have based on the [swagger documentation][1]:

```yaml
securityDefinitions:
  APIKey:
    type: apiKey
    name: Authorization
    in: header
security:
  - APIKey: []
```


  [1]: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#securityDefinitionsObject

How can I represent &#39;Authorization: Bearer &lt;token&gt;&#39; in a Swagger Spec (swagger.json)

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]
My pom.xml has the following entries

    &lt;dependency&gt;
        &lt;groupId&gt;io.springfox&lt;/groupId&gt;
        &lt;artifactId&gt;springfox-swagger2&lt;/artifactId&gt;
        &lt;version&gt;2.4.0&lt;/version&gt;
    &lt;/dependency&gt;

    &lt;dependency&gt;
        &lt;groupId&gt;io.springfox&lt;/groupId&gt;
        &lt;artifactId&gt;springfox-swagger-ui&lt;/artifactId&gt;
        &lt;version&gt;2.4.0&lt;/version&gt;
    &lt;/dependency&gt;

SwaggerConfig :

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
	
	@Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).select()
        		.apis(RequestHandlerSelectors.any())
        		.paths(PathSelectors.any())
        		.build()
        		.apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(&quot;My REST API&quot;, &quot;Some custom description of API.&quot;, &quot;API TOS&quot;, &quot;Terms of service&quot;, &quot;myeaddress@company.com&quot;, &quot;License of API&quot;, &quot;API license URL&quot;);
        return apiInfo;
    }

AppConfig:

    @Configuration
    @EnableWebMvc
    @ComponentScan(basePackages = { &quot;com.musigma.esp2&quot; })
    @Import(SwaggerConfig.class)
    public class AppConfig extends WebMvcConfigurerAdapter {

    // ========= Overrides ===========

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new LocaleChangeInterceptor());
    }
    
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler(&quot;swagger-ui.html&quot;)
          .addResourceLocations(&quot;classpath:/META-INF/resources/&quot;);
     
        registry.addResourceHandler(&quot;/webjars/**&quot;)
          .addResourceLocations(&quot;classpath:/META-INF/resources/webjars/&quot;);
    }

web.xml entries:

    &lt;context-param&gt;
		&lt;param-name&gt;contextConfigLocation&lt;/param-name&gt;
		&lt;param-value&gt;
			com.musigma.esp2.configuration.AppConfig
			com.musigma.esp2.configuration.WebSecurityConfiguration
			com.musigma.esp2.configuration.PersistenceConfig
			com.musigma.esp2.configuration.ACLConfig
			com.musigma.esp2.configuration.SwaggerConfig
		&lt;/param-value&gt;
	&lt;/context-param&gt;

WebSecurityConfig:

    @Configuration
    @EnableWebSecurity
    @EnableGlobalMethodSecurity(prePostEnabled = true)
    @ComponentScan(basePackages = { &quot;com.musigma.esp2.service&quot;, &quot;com.musigma.esp2.security&quot; })
    public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {
    @Override
    	protected void configure(HttpSecurity httpSecurity) throws Exception {
    		httpSecurity
    		.csrf()
    			.disable()
    		.exceptionHandling()
    			.authenticationEntryPoint(this.unauthorizedHandler)
    			.and()
    		.sessionManagement()
    			.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
    			.and()
    		.authorizeRequests()
    			.antMatchers(&quot;/auth/login&quot;, &quot;/auth/logout&quot;).permitAll()
    			.antMatchers(&quot;/api/**&quot;).authenticated()
    			.anyRequest().authenticated();
    
    		// custom JSON based authentication by POST of {&quot;username&quot;:&quot;&lt;name&gt;&quot;,&quot;password&quot;:&quot;&lt;password&gt;&quot;} which sets the token header upon authentication
    		httpSecurity.addFilterBefore(loginFilter(), UsernamePasswordAuthenticationFilter.class);
    
    		// custom Token based authentication based on the header previously given to the client
    		httpSecurity.addFilterBefore(new StatelessTokenAuthenticationFilter(tokenAuthenticationService), UsernamePasswordAuthenticationFilter.class);
    	}
    }

  [1]: http://i.stack.imgur.com/z8Hl1.png

How to configure Spring Security to allow Swagger URL to be accessed without authentication

I have JSON schema file where one of the properties is defined as either `string` or `null`:

    &quot;type&quot;:[&quot;string&quot;, &quot;null&quot;]

When converted to YAML (for use with OpenAPI/Swagger), it becomes:

&lt;!-- language: lang-yaml --&gt;

    type:
      - &#39;null&#39;
      - string

but the Swagger Editor shows an error:

&gt; Schema &quot;type&quot; key must be a string

What is the correct way to define a nullable property in OpenAPI?

How to define a property that can be string or null in OpenAPI (Swagger)?

For some REST APIs written in PHP, I was asked to create [Swagger][1] documentation, and since I was not aware of any easy way of adding annotations to those existing APIs and create such a documentation, I used [this editor][2] to generate some for now.

I saved the JSON and YAML files created using that editor, and now I need to create the final interactive Swagger documentation (this statement might sound naive and vague).

Can someone please let me know how I can convert the Swagger JSON specification file to actual Swagger documentation? 

I am on the Windows platform and do not know anything about Ant/Maven.

  [1]: http://swagger.io
  [2]: http://editor.swagger.io/

Converting Swagger specification JSON to HTML documentation

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 response and want to use it as `Authorization` header value in requests to all urls if it&#39;s present, and to `/products` as an example.

Should I create a text input manually somewhere on the Swagger UI page, then put the token there and somehow inject in the requests or are there tools to manage it in a better way?

How to send custom headers with requests in Swagger UI?

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 release I would like to document this API in swagger, how would I do that? Is there a way that I can generate swagger based off of the postman export?

How can I generate swagger based off of existing postman collection?

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 &#39;~/swagger/docs/v1&#39;.  However, I am not getting any output.

I started with a brand new ASP.NET Core API project. I should mention this is ASP.NET Core 2. The API works, and I am able to retrieve values from the values controller just fine.  

My startup class has the configuration exactly as described in this article ([Swashbuckle.AspNetCore on GitHub][1]).

    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();

            services.AddSwaggerGen(c =&gt;
            {
                c.SwaggerDoc(&quot;v1&quot;, new Info { Title = &quot;My API&quot;, Version = &quot;v1&quot; });
            });
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();

                // Enable middleware to serve generated Swagger as a JSON endpoint.
                app.UseSwagger();
                app.UseSwaggerUI(c =&gt;
                {
                    c.SwaggerEndpoint(&quot;/swagger/v1/swagger.json&quot;, &quot;MyAPI V1&quot;);
                });
            }
            else
            {
                app.UseExceptionHandler();
            }

            app.UseStatusCodePages();
            app.UseMvc();

            //throw new Exception();
        }
    }

You can see the NuGet references...

[![enter image description here][2]][2]

Again, this is all the default template, but I include the ValuesController for reference...

    [Route(&quot;api/[controller]&quot;)]
    public class ValuesController : Controller
    {
        // GET api/values
        [HttpGet]
        public IEnumerable&lt;string&gt; Get()
        {
            return new string[] { &quot;value1&quot;, &quot;value2&quot; };
        }

        // GET api/values/5
        [HttpGet(&quot;{id}&quot;)]
        public string Get(int id)
        {
            return &quot;value&quot;;
        }

        // POST api/values
        [HttpPost]
        public void Post([FromBody]string value)
        {
        }

        // PUT api/values/5
        [HttpPut(&quot;{id}&quot;)]
        public void Put(int id, [FromBody]string value)
        {
        }

        // DELETE api/values/5
        [HttpDelete(&quot;{id}&quot;)]
        public void Delete(int id)
        {
        }
    }


  [1]: https://github.com/domaindrivendev/Swashbuckle.AspNetCore
  [2]: https://i.stack.imgur.com/WYiRf.png

ASP.NET Core - Swashbuckle not creating swagger.json 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: &quot;2017-01-01&quot;
        format: date

But I see a lot of declarations like these:

      startDate:
        type: string
        description: Start date
        example: &quot;2017-01-01&quot;
        format: date
        pattern: &quot;YYYY-MM-DD&quot;
        minLength: 0
        maxLength: 10

Thanks.

What is the correct way to declare a date in an OpenAPI / Swagger-file?

Let&#39;s say I&#39;ve got a parameter like `limit`. This one gets used all over the place and it&#39;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 results
          required: false
          type: number
          format: int32

Can I use $ref to define this elsewhere and make it reusable? I came across [this ticket](https://github.com/swagger-api/swagger-spec/issues/171) which suggests that someone wants to change or improve feature, but I can&#39;t tell if it already exists today or not?


Swagger/OpenAPI - use $ref to pass a reusable defined parameter

How can I export a Swagger definition file? It should be a JSON or YAML file, e.g. swagger.json or swagger.yaml.

Let&#39;s say I have an endpoint looking like `http://example.com//swagger/ui/index#!`:

[![enter image description here][1]][1]

The version is `api version: v1`.

There is no &quot;Export&quot; button that I can see. So how do I export it?

  [1]: https://i.stack.imgur.com/2Tupn.png

How to export swagger.json (or yaml)

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).

What&#39;s the easiest way to do this? I&#39;m not a backend guy.

Swagger/OpenAPI mock server

In my &quot;simplified&quot; API, all responses are derived (*inherit*) from a base &quot;response&quot; 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) is laid out such that all the metadata is on the first &quot;layer&quot; and the body is a single attribute called &quot;body&quot; as such

    response
    |--metadata attribute 1 (string/int/object)
    |--metadata attribute 2 (string/int/object)
    |--body (object)
        |--body attribute 1 (string/int/object)
        |--body attribute 2 (string/int/object)

I have tried to define this relationship in swagger with the following JSON:

    {
        ...
        &quot;definitions&quot;: {
            &quot;response&quot;: {
                &quot;allOf&quot;: [
                    {
                        &quot;$ref&quot;: &quot;#/definitions/response_header&quot;
                    },
                    {
                        &quot;properties&quot;: {
                            &quot;body&quot;: {
                                &quot;description&quot;: &quot;The body of the response (not metadata)&quot;,
                                &quot;schema&quot;: {
                                    &quot;$ref&quot;: &quot;#/definitions/response_body&quot;
                                }
                            }
                        }
                    }
                ]
            },
            &quot;response_header&quot;: {
                &quot;type&quot;: &quot;object&quot;,
                &quot;required&quot;: [
                    &quot;result&quot;
                ],
                &quot;properties&quot;: {
                    &quot;result&quot;: {
                        &quot;type&quot;: &quot;string&quot;,
                        &quot;description&quot;: &quot;value of &#39;success&#39;, for a successful response, or &#39;error&#39; if there is an error&quot;,
                        &quot;enum&quot;: [
                            &quot;error&quot;,
                            &quot;success&quot;
                        ]
                    },
                    &quot;message&quot;: {
                        &quot;type&quot;: &quot;string&quot;,
                        &quot;description&quot;: &quot;A suitable error message if something went wrong.&quot;
                    }
                }
            },
            &quot;response_body&quot;: {
                &quot;type&quot;: &quot;object&quot;
            }
        }
    }

I then try to create different responses by creating the various body/header classes that inherit from body/header, and then create child response classes that are composed of the relevant header/body classes (shown in source code at bottom). However, I am certain that either this is the wrong way to do things, or that my implementation is incorrect. I have been unable to find an example of inheritance in the [swagger 2.0 specification][1] (shown below) but have found an example of [composition][2].

![enter image description here][3]

I am pretty certain that this &quot;discriminator&quot; has a large part to play, but not sure what I need to do. 

## Question
Could someone show me how one is supposed to implement composition+inheritance in swagger 2.0 (JSON), preferably by &quot;fixing&quot; my example code below. It would also be great if I could specify an ErrorResponse class that inherits from response where the &quot;result&quot; attribute in the header is always set to &quot;error&quot;.


    {
        &quot;swagger&quot;: &quot;2.0&quot;,
        &quot;info&quot;: {
            &quot;title&quot;: &quot;Test API&quot;,
            &quot;description&quot;: &quot;Request data from the system.&quot;,
            &quot;version&quot;: &quot;1.0.0&quot;
        },
        &quot;host&quot;: &quot;xxx.xxx.com&quot;,
        &quot;schemes&quot;: [
            &quot;https&quot;
        ],
        &quot;basePath&quot;: &quot;/&quot;,
        &quot;produces&quot;: [
            &quot;application/json&quot;
        ],
        &quot;paths&quot;: {
            &quot;/request_filename&quot;: {
                &quot;post&quot;: {
                    &quot;summary&quot;: &quot;Request Filename&quot;,
                    &quot;description&quot;: &quot;Generates an appropriate filename for a given data request.&quot;,
                    &quot;responses&quot;: {
                        &quot;200&quot;: {
                            &quot;description&quot;: &quot;A JSON response with the generated filename&quot;,
                            &quot;schema&quot;: {
                                &quot;$ref&quot;: &quot;#/definitions/filename_response&quot;
                            }
                        }
                    }
                }
            }
        },
        &quot;definitions&quot;: {
            &quot;response&quot;: {
                &quot;allOf&quot;: [
                    {
                        &quot;$ref&quot;: &quot;#/definitions/response_header&quot;
                    },
                    {
                        &quot;properties&quot;: {
                            &quot;body&quot;: {
                                &quot;description&quot;: &quot;The body of the response (not metadata)&quot;,
                                &quot;schema&quot;: {
                                    &quot;$ref&quot;: &quot;#/definitions/response_body&quot;
                                }
                            }
                        }
                    }
                ]
            },
            &quot;response_header&quot;: {
                &quot;type&quot;: &quot;object&quot;,
                &quot;required&quot;: [
                    &quot;result&quot;
                ],
                &quot;properties&quot;: {
                    &quot;result&quot;: {
                        &quot;type&quot;: &quot;string&quot;,
                        &quot;description&quot;: &quot;value of &#39;success&#39;, for a successful response, or &#39;error&#39; if there is an error&quot;,
                        &quot;enum&quot;: [
                            &quot;error&quot;,
                            &quot;success&quot;
                        ]
                    },
                    &quot;message&quot;: {
                        &quot;type&quot;: &quot;string&quot;,
                        &quot;description&quot;: &quot;A suitable error message if something went wrong.&quot;
                    }
                }
            },
            &quot;response_body&quot;: {
                &quot;type&quot;: &quot;object&quot;
            },
            &quot;filename_response&quot;: {
                &quot;extends&quot;: &quot;response&quot;,
                &quot;allOf&quot;: [
                    {
                        &quot;$ref&quot;: &quot;#definitions/response_header&quot;
                    },
                    {
                        &quot;properties&quot;: {
                            &quot;body&quot;: {
                                &quot;schema&quot;: {
                                    &quot;$ref&quot;: &quot;#definitions/filename_response_body&quot;
                                }
                            }
                        }
                    }
                ]
            },
            &quot;filename_response_body&quot;: {
                &quot;extends&quot;: &quot;#/definitions/response_body&quot;,
                &quot;properties&quot;: {
                    &quot;filename&quot;: {
                        &quot;type&quot;: &quot;string&quot;,
                        &quot;description&quot;: &quot;The automatically generated filename&quot;
                    }
                }
            }
        }
    }

### Diagram Update
To try and clarify what I want, I have created the very basic diagram below which aims to show that all responses are instantiations of the &quot;response&quot; object that have been built by (composition) using any combination of response_header and response_body objects. The response_header and response_body objects can be extended and inserted into any response object, which is done in the case of a filename_response which uses the filename_response_body child of the base response_body class. Both error and successful responses use the &quot;response&quot; object.

![enter image description here][4]


  [1]: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md
  [2]: https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/models/modelWithComposition.json
  [3]: http://i.stack.imgur.com/zPJN4.png
  [4]: http://i.stack.imgur.com/gqQUQ.png

Swagger Inheritance and Composition

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
    {
        [Route(&quot;/error&quot;)]
        public IActionResult Index()
        {
            return StatusCode(500, new Error(&quot;Internal error.&quot;));
        }
    }

When I started the app with this method, the following message showed up:

&gt; Failed to load API definition.
&gt;
&gt; Errors  
&gt; Fetch error Internal Server Error /swagger/v1/swagger.json

As soon as I explicitly set e.g. `[HttpGet]` the error disappears. The problem with this is, I need this method to fire for all possible HTTP operations. 
Of course, I could specify all operations explicitly, but I have the feeling Swagger should be able to handle this correctly.

Why does Swagger behave this way?

Is there any configuration I can use?

Swashbuckle/Swagger + ASP.Net Core: &quot;Failed to load API definition&quot;

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 portable at all.

Does anyone have a sample project (or a set of detailed steps) that can help me accomplish this? In particular, I am looking for a good sample that uses swagger-springmvc. I know it has &#39;samples&#39;, but at best, the esoteric code is discouraging.

I must clarify that I am not looking for &quot;why Swagger is simply the best&quot;. I am not using (and for my current task will not use) Spring Boot or such.

A &#39;simple&#39; way to implement Swagger in a Spring MVC application

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
&gt;500 : { &quot;Message&quot;: &quot;An error has occurred.&quot; } /api/swagger/docs/v1

[![enter image description here][1]][1]
The deployment is to `default web site/api`

Im guessing it has something to do with the baseUrl or something like that,
but I have no idea of even where to begin.

My routes work fine within the project - I can call all my webapi endpoints and they respond correctly.

any help would be much appreciated


  [1]: http://i.stack.imgur.com/T5kJU.jpg

swagger-ui returns 500 after deployment

I have Swagger API Declaration for services using [Swagger v 1.2](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md).

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 objects.

However, while part of the Swagger reuses JSON Schema structures, it turned out that it uses only a subset of features, and it also introduces its own inheritance in Models (using `subTypes` and `discriminator`).

Question: Is there any existing project or piece of code which can **generate usable JSON Schema from Swagger API Declaration**?

Optimally JSON Schema Draft 4 and using Python (but I will be happy to find anything).

How to generate JSON-Schema from Swagger API Declaration

Is there a method for creating static documentation for swagger 2.0?
Perhaps like the &#39;preview&#39; on editor.swagger.io.


I need to get static html files so I can include them in some static documents.

So far I&#39;ve not found a way to do this. I see there is swagger-codegens static-docs
but this only works for swagger &lt;= 1.2.

Generate static docs with swagger

I have a swagger 2.0 resource defined below. How can I make &quot;param1 or param2&quot; required? Caller has to pass either param1 or param2.

    /some/res:
    put:
      summary: some resource
      responses:
        200:
          description: Successful response
          schema:
            $ref: &#39;#/definitions/SomeResponse&#39;
      parameters:
        - name: param1
          type: string
          description: param1
          in: formData
          required: false
        - name: param2
          type: string
          description: param2
          in: formData
          required: false

Swagger 2.0 - how to make &quot;one or the other&quot; parameter required?

I have added Swagger to my Spring Boot 2 application:

This is my Swagger config:

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
        @Bean
        public Docket api() {
    	    // @formatter:off
            return new Docket(DocumentationType.SWAGGER_2)  
                    .select()                                  
                    .apis(RequestHandlerSelectors.any())              
                    .paths(PathSelectors.any())                          
                    .build();
            // @formatter:on
        }
    }

This is Maven dependency:

    &lt;!-- Swagger2 --&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;io.springfox&lt;/groupId&gt;
        &lt;artifactId&gt;springfox-swagger2&lt;/artifactId&gt;
        &lt;version&gt;2.8.0&lt;/version&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;io.springfox&lt;/groupId&gt;
        &lt;artifactId&gt;springfox-swagger-ui&lt;/artifactId&gt;
        &lt;version&gt;2.8.0&lt;/version&gt;
    &lt;/dependency&gt;

When I try to invoke for example http://localhost:8080/api/actuator/auditevents  it fails with the following error:

    TypeError: Failed to execute &#39;fetch&#39; on &#39;Window&#39;: Request with GET/HEAD method cannot have body.

[![enter image description here][1]][1]

What am I doing wrong and how to fix it ?

  [1]: https://i.stack.imgur.com/4EyaE.png

Swagger TypeError: Failed to execute &#39;fetch&#39; on &#39;Window&#39;: Request with GET/HEAD method cannot have body

In Swagger, the [`@Api`](https://www.javadoc.io/static/io.swagger/swagger-annotations/1.6.2/io/swagger/annotations/Api.html) annotation&#39;s [`description`](https://www.javadoc.io/static/io.swagger/swagger-annotations/1.6.2/io/swagger/annotations/Api.html#description--) element is deprecated.

&gt; **Deprecated.**
&gt; Not used in 1.5.X, kept for legacy support.

Is there a newer way of providing the description?

Api annotation&#39;s description is deprecated

I&#39;m trying to open my self generated swagger specification file `my.json` with [swagger-ui][1] on my local computer.

So I [downloaded][2] 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. Now I opened the `index.html` and want to explore `my.json`. And here the problem begins:

[![File in windows explorer][3]][4] [![Enter path to file in bar][5]][6] [![Will be prefixed by current url and cannot find the file][7]][8]

If I enter a local path, it always will be prefixed by the current url containing the `index.html`. And therefor I can&#39;t open my file. I tried all following combinations without success:

- `my.json` leads to `file:///D:/swagger-ui/dist/index.html/my.json`
- `file:///D:/swagger-ui/dist/my.json` leads to `file:///D:/swagger-ui/dist/index.html/file:///D:/swagger-ui/dist/my.json`
 

  [1]: https://github.com/swagger-api/swagger-ui
  [2]: https://github.com/swagger-api/swagger-ui/archive/v2.1.8-M1.zip
  [3]: http://i.stack.imgur.com/0Gh9ls.png
  [4]: http://i.stack.imgur.com/0Gh9l.png
  [5]: http://i.stack.imgur.com/mUlCbs.png
  [6]: http://i.stack.imgur.com/mUlCb.png
  [7]: http://i.stack.imgur.com/j9bfas.png
  [8]: http://i.stack.imgur.com/j9bfa.png

How to open local files in Swagger-UI

I&#39;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&#39;t use JsonIgnore attribute because the legacy interfaces also need to serialize to JSON so I don&#39;t want to ignore the properties globally, just in the Swashbuckle configuration.

I found a method of doing this documented here:

https://github.com/domaindrivendev/Swashbuckle/issues/73

But this appears to be out of date with the current Swashbuckle release. 

The method recommended for the old version of Swashbuckle is using an IModelFilter implementation as follows:


    public class OmitIgnoredProperties : IModelFilter
    {
        public void Apply(DataType model, DataTypeRegistry dataTypeRegistry, Type type)
        {
            var ignoredProperties = … // use reflection to find any properties on 
                                      // type decorated with the ignore attributes

            foreach (var prop in ignoredProperties) 
                model.Properties.Remove(prop.Name);

        }
    }
    
    SwaggerSpecConfig.Customize(c =&gt; c.ModelFilter&lt;OmitIgnoredProperties&gt;());

But I&#39;m unsure how to configure Swashbuckle to use the IModelFilter in the current version?  I&#39;m using Swashbuckle 5.5.3. 


How to configure Swashbuckle to ignore property on model

I would like to format my Swagger API descriptions so that they are not simple paragraphs of text.  Preferably, I&#39;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 [Swagger Editor][1], and open the Instagram example (File \ Open Example \ Instagram.yaml), I see the the first description in the yaml file shows some formatting including a hyperlink and bounding box:

        [registered your client](http://instagram.com/developer/register/) it&#39;s easy
    to start requesting data from Instagram.

    ```
      https://api.instagram.com/v1/media/popular?client_id=CLIENT-ID
    ```

This looks like standard [Markdown][2], but when I add a table markdown to the samples description, the editor presents an error:

    |Col1|Col2|
    |------|------|
    |1|2|

    
    YAML Syntax Error
    End of the stream or a document separator is expected at line 36, column

What formatting does Swagger 2.0 allow?
Am I doing something wrong to render a table?


  [1]: http://editor.swagger.io/#/
  [2]: https://en.wikipedia.org/wiki/Markdown

How to format Swagger 2.0 text descriptions?

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:

&lt;!-- language: lang-json --&gt;

    {
           &quot;name&quot;: &quot;File&quot;,
           &quot;description&quot;: &quot;The file in zip format.&quot;,
           &quot;paramType&quot;: &quot;body&quot;,
           &quot;required&quot;: true,
           &quot;allowMultiple&quot;: false,
           &quot;dataType&quot;: &quot;file&quot;
    }

and now I see the file upload option on my Swagger UI page. But when I select a file and click &quot;try it out&quot;, I get the following error:

&gt; NS_ERROR_XPC_BAD_OP_ON_WN_PROTO: Illegal operation on WrappedNative prototype object in jquery-1.8.0.min.js (line 2)

The page is continuously processing and I am not getting any response.

Any ideas what could be wrong?

How to post files in Swagger (OpenAPI)?

How to I define in OpenAPI/Swagger if a field is optional or required and what is the default?

How to specify if a field is optional or required 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?&lt;br/&gt; [Example here](https://petstore.swagger.io/#!/pet/addPet) has an enum option for the `status` property.&lt;br/&gt; How to do define such an enum in OpenAPI 2.0?

How to define an enum in OpenAPI (Swagger)?

I like swagger for documenting Restful APIs very much, especially &quot;Try it out!&quot; button, but `swagger-ui` interface doesn&#39;t look very cool.

And I cannot believe there are no templates for such amazing open source tool (or I can&#39;t find any)?

I don&#39;t want it for free.. Like http://getbootstrap.com/ has many sites to buy themes (like https://wrapbootstrap.com/), why I cannot find any site for swagger themes?

Why there are no themes for swagger-ui?

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**, after I set the `required` as `false`.

I found out that if I set the `required` value as `true` the error will be gone. Here is a sample of my Swagger code.
   
    ...
    paths:
      &#39;/get/{param1}/{param2}&#39;:
        get:
          ...
          parameters:
          - name: param1
            in: path
            description: &#39;description regarding param1&#39;
            required: false
            type: string
          - name: param2
            in: path
            description: &#39;description regarding param2&#39;
            required: false
            type: string

I didn&#39;t experience this with parameters in body or the the ones in query. I think this problem is only related to parameters in path. I could not find any solution in swagger specification files either. 

Is there any other way to define optional parameters in Swagger or do I have any mistake in my code?

Any help would be appreciated.

How to define an optional parameter in path using swagger

This question is not a duplicate of (https://stackoverflow.com/questions/27844127/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 a 200 whose schema is different based on whether the parameter was passed, e.g.,:

    GET /endpoint -&gt; {200, schema_1}
    GET /endpoint?selector=blah  -&gt; {200, schema_2}

In the yaml, I tried having two 200 codes, but the viewer squashes them down as if I only specified one. 

Is there a way to do this?

Edit: the following seems related: https://github.com/OAI/OpenAPI-Specification/issues/270

Swagger; specify two responses with same code based on optional parameter

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 find a tool to validate against specs created in the Swagger (tool for creating API schema). The only solution I found is generating a client/server in the Swagger-Editor, it is quite cumbersome.

Is there already an existing tool to validate JSON against Swagger Schema?

Validating JSON against Swagger API schema

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 added the code below:

&lt;!-- language: lang-cs --&gt;

    services.AddSwaggerGen(c =&gt;
        {
            c.SwaggerDoc(&quot;v1&quot;, new Microsoft.OpenApi.Models.OpenApiInfo { Title = &quot;My Web API&quot;, Version = &quot;v1&quot; });
            c.AddSecurityDefinition(&quot;Bearer&quot;, new OpenApiSecurityScheme
            {
                Description = &quot;JWT Authorization header using the Bearer scheme. Example: \&quot;Authorization: Bearer {token}\&quot;&quot;,
                Name = &quot;Authorization&quot;,
                In = ParameterLocation.Header,
                Type = SecuritySchemeType.ApiKey
            });
        });

After adding `AddSecurityDefinition` function, I can see the Authorize button and when I click it, I see the form below:
[![enter image description here][1]][1]

Then I type `Bearer WhatEverApiKeyIsfgdgdgdg845734987fgdhgiher635kjh`. After doing it, I expect to see `authorization: Bearer WhatEverApiKeyIsfgdgdgdg845734987fgdhgiher635kjh` in the request&#39;s header when I send a request to the Web API from Swagger, but authorization is not added to the request header. I am using SwashBuckle.Swagger(5.0.0-rc3). Please note there are many samples which work fine on .NET Core 2.0, but Swashbuckle swagger functions has changed on the latest version so I cannot use those samples.


  [1]: https://i.stack.imgur.com/gNgds.png


JWT Authentication and Swagger with .NET Core 3.0

I have a REST services to document,
some of them accepts simple array like:

	[
	  { &quot;name&quot;:&quot;a&quot; },
	  { &quot;name&quot;:&quot;b&quot; },
	  { &quot;name&quot;:&quot;c&quot; }
	]

How do I describe this in Swagger model section ? I can only create &#39;named array&#39; like

    model {
    properties: { &quot;arr&quot;: { &quot;type&quot;:&quot;array&quot;, ......

but it describes data like this:

	&quot;arr&quot;: [
	  { &quot;name&quot;:&quot;a&quot; },
	  { &quot;name&quot;:&quot;b&quot; },
	  { &quot;name&quot;:&quot;c&quot; }
	]


How to describe a model in Swagger for an array with simple objects?

I inherited an existing API and I would like to document it with swagger, but I don&#39;t yet know the full scope of it. Can Swagger (or another middleware/tool) auto-magically generate the yaml (for swagger) based on the existing express routes?

For what I saw on other questions, it would appear that this is mostly a manual job, but I&#39;m double-checking if someone here found a way around this.

Can Swagger autogenerate its yaml based on existing express routes?

I have the following YAML fragment:

    description: |
      &quot;API for bean consuming applications.
      Examples: painted pony, lima bean&quot;

[Swagger editor][1] interprets the colon (`:`) as a special character, despite the quotation marks.

According to the accepted answer to [this question][2], the colon should not be treated as special character.

Is this a bug of Swagger or is an escape sequence needed to use the colon in quoted text literals?

I tried to find this out using the [YAML specification][3] but gave up.

How do I have to read that spec to answer the question?

Is there a difference between single quotes (`&#39;`) and double quotes (`&quot;`) in YAML?

Does the pipe (`|`) or the greater than (`&gt;`) construction only influence the line break handling or the handling of special characters, too?


  [1]: http://editor.swagger.io/#/
  [2]: https://stackoverflow.com/questions/11301650/how-to-escape-indicator-characters-i-e-or-in-yaml
  [3]: http://yaml.org/spec/

How to escape colons and other special characters in a YAML string?

By default when you enable swagger in ASP.NET Core project it&#39;s available on url:

    http://localhost:&lt;random_port&gt;/swagger/ui

I would like to use a different base url instead of `/swagger/ui`. How/where can i configure that?

I found that for older versions you can configure the `RootUrl` but there aren&#39;t similiar method in ASP.NET Core:
  
    .EnableSwagger(c =&gt;
    {
        c.RootUrl(req =&gt; myCustomBasePath);
    });

How to change base url of Swagger in ASP.NET core

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&#39;t find a clear one. 

While searching i found that the method `OperationFilter()` has to do something about it. 


Web Api How to add a Header parameter for all API in Swagger

I have swagger plugged in to my spring boot application.  Spring boot allows you to have property files for each environment that you have.  Is there a way to disable swagger for a production environment?

How do you turn off swagger-ui in production

I have the following schema definition:

&lt;!-- language: lang-yaml --&gt;

    swagger: &#39;2.0&#39;
    ...
    definitions:
      Service:
        type: object
        properties:
          serviceId:
            type: string
            description: Device or service identification number
            example: 1111111111      
          location:
            type: string
            description: Location of the service
            example: &#39;400 Street name, City State postcode, Country&#39;

I would like to do annotate the `location` field as deprecated. Is there a way to do this?

How to annotate a field as deprecated in OpenAPI (Swagger) 2.0?

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. Both of them seem to be RESTful specifications. Which one is widely used?


What is Swagger and does it relate to OData?

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 documentation (based on Swagger rules).
 - Swagger UI displays the documentation. It uses Swashbuckle to do this.

Is this information correct?  If not can someone explain in simple terms what Swagger, Swashbuckle, and Swashbuckle UI mean? 

Also, what do I lose as an API developer if I do not use this?

What is Swagger, Swashbuckle and Swashbuckle UI

I am creating a REST Api using Spring boot, and auto generating the swagger documentation in controllers using swagger codegen. However, I am not able to set a description and example for a parameter of type String in a POST request. Here is mi code:
    
    import io.swagger.annotations.*;
    
    @Api(value = &quot;transaction&quot;, tags = {&quot;transaction&quot;})
    @FunctionalInterface
    public interface ITransactionsApi {
        @ApiOperation(value = &quot;Places a new transaction on the system.&quot;, notes = &quot;Creates a new transaction in the system. See the schema of the Transaction parameter for more information &quot;, tags={ &quot;transaction&quot;, })
        @ApiResponses(value = {
            @ApiResponse(code = 200, message = &quot;Another transaction with the same messageId already exists in the system. No transaction was created.&quot;),
            @ApiResponse(code = 201, message = &quot;The transaction has been correctly created in the system&quot;),
            @ApiResponse(code = 400, message = &quot;The transaction schema is invalid and therefore the transaction has not been created.&quot;, response = String.class),
            @ApiResponse(code = 415, message = &quot;The content type is unsupported&quot;),
            @ApiResponse(code = 500, message = &quot;An unexpected error has occurred. The error has been logged and is being investigated.&quot;) })
    
        @RequestMapping(value = &quot;/transaction&quot;,
            produces = { &quot;text/plain&quot; },
            consumes = { &quot;application/json&quot; },
            method = RequestMethod.POST)
        ResponseEntity&lt;Void&gt; createTransaction(
            @ApiParam(
                value = &quot;A JSON value representing a transaction. An example of the expected schema can be found down here. The fields marked with an * means that they are required.&quot; ,
                example = &quot;{foo: whatever, bar: whatever2}&quot;)
            @Valid @RequestBody String kambiTransaction) throws InvalidTransactionException;
    }

**The example property of the @ApiParam has been manually inserted by me, because the codegen was ignoring that part of the yaml (That is another question: why is the editor ignoring the example part?).** Here is part of the yaml:

    paths:
      /transaction:
        post:
          tags:
            - transaction
          summary: Place a new transaction on the system.
          description: &gt;
            Creates a new transaction in the system. See the schema of the Transaction parameter
            for more information
          operationId: createTransaction
          parameters:
            - $ref: &#39;#/parameters/transaction&#39;
          consumes:
            - application/json
          produces:
            - text/plain
          responses:
            &#39;200&#39;:
              description: Another transaction with the same messageId already exists in the system. No transaction was created.
            &#39;201&#39;:
              description: The transaction has been correctly created in the system
            &#39;400&#39;:
              description: The transaction schema is invalid and therefore the transaction has not been created.
              schema:
                type: string
                description: error message explaining why the request is a bad request.
            &#39;415&#39;:
              description: The content type is unsupported
            &#39;500&#39;:
              $ref: &#39;#/responses/Standard500ErrorResponse&#39;

    parameters:
      transaction:
        name: kambiTransaction
        in: body
        required: true
        description: A JSON value representing a kambi transaction. An example of the expected schema can be found down here. The fields marked with an * means that they are required.
        schema:
          type: string
          example:
            {
              foo*: whatever,
              bar: whatever2
            }

And finally, this is what swagger is showing:

[![enter image description here][1]][1]

Finally, the dependencies used in build.gradle are the following ones:

    compile group: &#39;io.springfox&#39;, name: &#39;springfox-swagger2&#39;, version: &#39;2.7.0&#39;
    compile group: &#39;io.springfox&#39;, name: &#39;springfox-swagger-ui&#39;, version: &#39;2.7.0&#39;

**So, Question is:**
Does anybody know how I can set the description and an example of a body parameter using swagger annotations?

***EDIT***

I&#39;ve achieved to change the description using @ApiImplicitParam instead of @ApiParam, but example is still missing:

    @ApiImplicitParams({
        @ApiImplicitParam(
            name = &quot;kambiTransaction&quot;,
            value = &quot;A JSON value representing a transaction. An example of the expected schema can be found down here. The fields marked with * means that they are required. See the schema of KambiTransaction for more information.&quot;,
            required = true,
            dataType = &quot;String&quot;,
            paramType = &quot;body&quot;,
            examples = @Example(value = {@ExampleProperty(mediaType = &quot;application/json&quot;, value = &quot;{foo: whatever, bar: whatever2}&quot;)}))})


  [1]: https://i.stack.imgur.com/uw5ZU.png

How can I set a description and an example in Swagger with Swagger annotations?

I am try to create a swagger file with the following path:
    paths:
       /v1/customers/{id}/summary :

However I get the following error right off bat:

API requires path parameter but it is not defined: id
at paths ▹ /v1/customers/{id}/summary

It does not seem to like the &#39;id&#39; parameter. Could anybody tell me how I could rectify this?

If I drill down on this I see the following:

    Details
     Object
     swaggerError: Object
     errors: Array [1]
     0: Object
    code:  &quot;MISSING_API_PATH_PARAMETER&quot;
    message:  &quot;API requires path parameter but it is not defined: id&quot;
    data:  &quot;/v1/customers/{id}/summary&quot;
     path: Array [2]
     warnings: Array [0]

All Swagger Solutions on Gang of Coders

Total of 44 Swagger Solutions