Stack Overflow
Stack Overflow

Questions tagged [openapi]

The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful Web services.

A variety of tools can generate code, documentation and test cases given an interface file. Development of the OpenAPI Specification (OAS) is overseen by the Open API Initiative, an open source collaborative project of the Linux Foundation.

Ref: https://en.wikipedia.org/wiki/OpenAPI_Specification

Related tags

4284 questions
64
votes
1 answer

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": ""} B. {"id": null} C. {} This boils down to the question…
Marcel Stör
  • 22,695
  • 19
  • 92
  • 198
62
votes
2 answers

Migrating from Springfox Swagger 2 to Springdoc Open API

I try to follow these: https://www.dariawan.com/tutorials/spring/documenting-spring-boot-rest-api-springdoc-openapi-3/ How do I deal with annotations like: @ApiModel(value = "Response container") @ApiModelProperty(value = "Iventory response",…
Kalpesh Soni
  • 6,879
  • 2
  • 56
  • 59
61
votes
6 answers

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 additional properties additionalProperty: type,…
Emanuel Ey
  • 2,724
  • 5
  • 30
  • 38
58
votes
15 answers

Is it possible to add Authentication to access to NestJS' Swagger Explorer

I'm currently using Swagger in my NestJS project, and I have the explorer enabled: in main.js const options = new DocumentBuilder() .setTitle('My App') .setSchemes('https') .setDescription('My App API documentation') …
josec89
  • 1,932
  • 1
  • 16
  • 19
56
votes
1 answer

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. Both of them seem to be RESTful specifications.…
Muthukumar
  • 8,679
  • 17
  • 61
  • 86
52
votes
4 answers

Swagger: map of

I need to document with Swagger an API that uses, both as input and output, maps of objects, indexed by string keys. Example: { "a_property": { "foo": { "property_1": "a string 1", "property_2": "a string 2" …
Xavier Lamorlette
  • 1,152
  • 1
  • 12
  • 20
49
votes
4 answers

Enable Authorize button in springdoc-openapi-ui for Bearer Token Authentication (JWT)

How to enable "Authorize" button in springdoc-openapi-ui (OpenAPI 3.0 /swagger-ui.html) for Bearer Token Authentication, for example JWT. What annotations have to be added to Spring @Controller and @Configuration classes?
Eugene Khyst
  • 9,236
  • 7
  • 38
  • 65
49
votes
2 answers

Why `additionalProperties` is the way to represent Dictionary/Map in Swagger/OpenAPI 2.0

Although I have seen the examples in the OpenAPI spec: type: object additionalProperties: $ref: '#/definitions/ComplexModel' it isn't obvious to me why the use of additionalProperties is the correct schema for a Map/Dictionary. It also doesn't…
Chen Levy
  • 15,438
  • 17
  • 74
  • 92
49
votes
3 answers

How to describe this POST JSON request body in OpenAPI (Swagger)?

I have a POST request that uses the following JSON request body. How can I describe this request body using OpenAPI (Swagger)? { "testapi":{ "testapiContext":{ "messageId":"kkkk8", "messageDateTime":"2014-08-17T14:07:30+0530" …
Anirban Sen Chowdhary
  • 8,233
  • 6
  • 39
  • 81
48
votes
4 answers

How to document GraphQL with Swagger \ OpenAPI?

How to document GraphQL with Swagger? We have a huge backend REST API which is recently has partially started to use GraphQL. For documenting API we're using Swagger. The question is: how to use Swagger(OpenAPI) for documenting GraphQL…
user12367662
  • 547
  • 1
  • 4
  • 4
48
votes
4 answers

How to define mutually exclusive query parameters in Swagger (OpenAPI)?

I have a series of parameters in Swagger like this "parameters": [ { "name": "username", "description": "Fetch username by username/email", …
lorless
  • 4,126
  • 8
  • 30
  • 41
46
votes
1 answer

How to convert OpenAPI 2.0 to OpenAPI 3.0?

Are there any tools/libraries to convert OpenAPI 2.0 definitions to OpenAPI 3.0, without doing it one per row?
Rumesh Madhusanka
  • 1,105
  • 3
  • 12
  • 26
45
votes
3 answers

How to specify a property can be null or a reference with swagger

How to specify a property as null or a reference? discusses how to specify a property as null or a reference using jsonschema. I'm looking to do the same thing with swagger. To recap the answer to the above, with jsonschema, one could do this: { …
djpinne
  • 673
  • 1
  • 6
  • 9
42
votes
6 answers

How do I include subclasses in Swagger API documentation/ OpenAPI specification using Swashbuckle?

I have an Asp.Net web API 5.2 project in c# and generating documentation with Swashbuckle. I have model that contain inheritance something like having an Animal property from an Animal abstract class and Dog and Cat classes that derive from…
Paolo Vigori
  • 1,612
  • 1
  • 18
  • 32
41
votes
2 answers

Re-using model with different required properties

I have a path that uses complex models with almost identical properties for each http method. The problem is that I want to define some required properties for the request of PUT and POST, while no properties are required in GET response (as the…
NotNone
  • 661
  • 1
  • 8
  • 13
1
2
3
…
99 100