OpenAPI 2.0 OAS2 does not support multiple response schemas per status code. You can only have a single schema, for example, a free-form object (type: object without properties). OpenAPI 3.x In OAS3 you can use oneOf to define multiple possible request bodies or response bodies for the same operation: openapi: 3.0.0 … paths: /path: get: … Read more
The possibility to mark schemas and schema properties as deprecated was added in OpenAPI 3.0: openapi: 3.0.1 … components: schemas: Service: type: object properties: location: type: string description: Location of the service example: ‘400 Street name, City State postcode, Country’ deprecated: true # <——— If you use OpenAPI 2.0 (Swagger 2.0), the only thing you … Read more
“enum” works like this in OpenAPI 2.0: { “in”: “query”, “name”: “sample”, “description”: “a sample parameter with an enum value”, “type”: “string”, “enum”: [ “1”, “2”], “required”: true } and in OpenAPI 3.0: { “in”: “query”, “name”: “sample”, “description”: “a sample parameter with an enum value”, “schema”: { “type”: “string”, “enum”: [ “1”, “2”] }, … Read more
I found two solutions for Spring Boot application: 1. Swagger 2 based: Firstly, use the tags method for specify the tags definitions in your Docket bean: @Configuration @EnableSwagger2 public class Swagger2Config { public static final String TAG_1 = “tag1”; @Bean public Docket productApi() { return new Docket(DocumentationType.SWAGGER_2).select() .apis(RequestHandlerSelectors.basePackage(“my.package”)).build() .tags(new Tag(TAG_1, “Tag 1 description.”)) // Other … Read more
Markdown is supported in the Swagger Editor. Below is an example of using Markdown in an OpenAPI (Swagger) document: swagger: ‘2.0’ info: version: 0.0.0 title: Markdown description: | # Heading Text attributes _italic_, *italic*, __bold__, **bold**, `monospace`. Horizontal rule: — Bullet list: * apples * oranges * pears Numbered list: 1. apples 2. oranges 3. … Read more
I could not get Adam Taras’s answer to work (i.e. using the relative path ../my.json). Here was my solution (pretty quick and painless if you have node installed): With Node, globally install package http-server npm install -g http-server Change directories to where my.json is located, and run the command http-server –cors (CORS has to be … Read more
I ran into this issue. Here is how I resolved it: I had a method like this: [HttpGet] public IEnumerable<MyObject> Get(MyObject dto) { … } and I was getting the error. I believe swagger UI is interpreting the Get parameters as FromBody, so it uses the curl -d flag. I added the [FromQuery] decorator and … Read more
This feature already exists in Swagger 2.0. The linked ticket talks about some specific mechanics of it which doesn’t affect the functionality of this feature. At the top level object (referred to as the Swagger Object), there’s a parameters property where you can define reusable parameters. You can give the parameter any name, and refer … Read more
An easy way to create simple mock from an OpenAPI (fka Swagger) spec without code is to use a tool call prism available at http://github.com/stoplightio/prism written in Typescript. This command line is all you need: ./prism run –mock –list –spec <your swagger spec file> The mock server will return a dynamic response based on the … Read more
APIMatic API Transformer can process a Postman collection (v1 or v2) as an input format and produce Swagger 1.2 or 2.0, and now OpenAPI 3.0.0 as output. It has its own API and a Web front-end, and also a command-line version.