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
14
votes
2 answers

VSCode indent in Swagger JSDoc

I'm using swagger-jsdoc with Express. Using this lib to describe an api end-point I use following lines in JSDock block in YAML: /** * @swagger * /users: * post: * summary: Register a user * tags: [Users] * description:…
Darkzarich
  • 470
  • 6
  • 18
14
votes
1 answer

How to require at least one of two parameters in OpenAPI?

I'm using OpenAPI 3 and have two query parameters, at least one of which is required but it doesn't matter which. I.e., as sudocode: if parameter_1 OR parameter_2: do stuff else: error Is this possible in OpenAPI 3? There's no mention of it…
GIS-Jonathan
  • 4,347
  • 11
  • 31
  • 45
14
votes
7 answers

What does the "Unrecognized token openapi" error mean when using OpenAPI Generator with OpenAPI 3.0?

I have written an API definition in the OpenAPI 3.0 format (https://swagger.io/docs/specification/basic-structure/). Now I'm trying to generate Java Spring objects as I was previously doing with a Swagger 2.0 definition and its associated Maven…
vpa
  • 341
  • 1
  • 2
  • 8
14
votes
1 answer

How do you convert an OpenAPI Spec (Swagger 2.0) to proto3?

I've done extensive Google searching but couldn't find a good tool to do this. The closest I could find was https://github.com/googleapis/gnostic, which allows converting an OpenAPI description (swagger.yaml) into a .pb file or a .json file. I'm…
Bob Risky
  • 805
  • 1
  • 9
  • 22
14
votes
1 answer

How to include Http request method name in client method names generated with NSwag

When I generate a C# client for an API using NSwag, where the API includes endpoints that can be used with multiple Http request types (e.g. POST, GET) the client generates a method for each request with the same base name, plus a number. E.g. Using…
Ergwun
  • 12,579
  • 7
  • 56
  • 83
14
votes
1 answer

Specifying multiple types for additionalProperties through Swagger/OpenAPI

I am looking to represent the following JSON Object in OpenAPI: { "name": "Bob", "age": 4, ... } The number of properties and the property names are not fully predetermined, so I look to use additionalProperties. However, I'm not too certain…
sle
  • 165
  • 1
  • 1
  • 8
14
votes
2 answers

How do I specify multiple hosts in OpenAPI (Swagger)?

Right now my OpenAPI 2.0 YAML file has only one host URL: host: petstore.test.com basePath: / Can I use multiple hosts like this? host1: petstore.test.com host2: petstore1.test.com host3: petstore2.dev.com
user2598740
  • 141
  • 1
  • 1
  • 5
13
votes
1 answer

openapi-generator-maven-plugin (Java) does not handle allOf properly

With org.openapitools:openapi-generator-maven-plugin, I have noticed that using allOf composed of multiple objects in a response does not generate a class combining these multiple objects. Instead it uses the first class defined in the allOf…
norbjd
  • 10,166
  • 4
  • 45
  • 80
13
votes
2 answers

In OpenAPI 3, how to document that an Accept header with a specified value is necessary on request in order for a successful API call?

For a legacy API that I document in order for a successful authentication I need to provide the following headers: X-Access-Token: {token} Accept: application/json; version=public/v2 For the token part I need document it via: openapi: 3.0.0 info: …
Dimitrios Desyllas
  • 9,082
  • 15
  • 74
  • 164
13
votes
2 answers

How do I change the Swagger default URL and use a custom one?

I have an API that I created in .NetCore 3.1 and have enabled Swagger(OAS3) using Swashbuckle. By default when my app starts if brings up the Swagger page using this URL: http://{port}/swagger.index.html I would like to customize the Swagger URL…
KSS
  • 821
  • 3
  • 10
  • 26
13
votes
3 answers

How to merge multiple OpenAPI specifications?

I'm digging here around trying to find a solution, how to merge several OpenApi v3 component definitions in one file. Let's imagine a situation: You decided to split your OpenApi into multiple files in different folders. (see image below) Now you…
P. Savrov
  • 1,064
  • 4
  • 17
  • 29
13
votes
2 answers

How is the operationId used from an OpenAPI schema?

In an OpenAPI schema, it includes the optional element operationId. How is this used and why is it optional? Well, at least with the .NET Core library "Swashbuckle" they say it's optional. My guess is that it is linked to how an SDK is consumed. For…
Pure.Krome
  • 84,693
  • 113
  • 396
  • 647
13
votes
5 answers

@ApiResponse with empty response body (Spring Boot)

I'm looking for a way to tell swagger that a certain API response code doesn't have a response body. A get response, for example, that can either return a 200 code with the actual object as a response or a 404 if the object associated with the…
valmarv
  • 854
  • 1
  • 8
  • 14
13
votes
2 answers

Swagger/OpenAPI annotations V3 - use Enum values in swagger annotations

I'm creating the the API description of our application using Swagger/OpenApi V3 annotations, imported from following dependency: org.springdoc springdoc-openapi-ui …
bramdc
  • 580
  • 1
  • 5
  • 21
13
votes
2 answers

How to dinstinctly document possible REST actions in ViewSet docstring?

The DRF docs mention this: Note that when using viewsets the basic docstring is used for all generated views. To provide descriptions for each view, such as for the the list and retrieve views, use docstring sections as described in Schemas…
rrauenza
  • 6,285
  • 4
  • 32
  • 57
1 2 3
…
99 100