Consider this OAS3 spec (testMinMax3.yaml):
openapi: 3.0.1
info:
title: OpenAPI Test
description: Test
license:
name: Apache-2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.0
servers:
- url: http://localhost:9999/v2
paths:
/ping:
post:
summary: test
description: test it
operationId: pingOp
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SomeObj'
required: true
responses:
200:
description: OK
content: {}
components:
schemas:
SomeObj:
type: string
minLength: 1
maxLength: 3
Does non-empty (aka minLength: 1) implies required even if a field is not set based on the openapi spec (1)? Or does that apply only if a value for the field is provided by the user (2)?
No.
minLength and required are separate constraints. minLength means that if a string value is provided, its length must be minLength or more.
Related
I run into problem while trying to instruct Dredd to issue a different requests to trigger two distinct scenarios: success with code 201 and failure with code 400.
I tried to setup a separate example per HTTP status code but couldn't manage to do that.
I can add example section in requestBody but then it will be used in both example - for success and failure.
openapi: 3.0.2
info:
description: Body example per HTTP code illustration
version: 1.0.0
title: Profile
tags:
- name: profile
description: User profiles
paths:
/profiles:
post:
tags:
- profiles
summary: Create profile
operationId: createProfile
requestBody:
description: Create Profile
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProfile'
required: true
responses:
'201':
description: Successful operation
headers:
Location:
schema:
type: string
description: Profile location
'400':
description: Profile is invalid (missing fields/null values)
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileCreationError'
examples:
failing_scenrio:
summary: An example tailored to work with Dredd
value:
name: can't be blank
email: can't be blank
components:
schemas:
CreateProfile:
type: object
required:
- name
- email
- age
properties:
name:
type: string
email:
type: string
age:
type: integer
format: int32
minimum: 0
ProfileCreationError:
type: object
properties:
name:
type: string
email:
type: string
age:
type: integer
I would like to be able to run tests for both HTTP codes: 201 and 400. Bonus points for an example of how to do same thing with path param. For example, to provide both found and not found examples for /profiles/{id} (i.e. 200 and 404).
The OpenAPI 3 support is currently (July 2019, Dredd v11.2.9) experimental and this particular behavior is still undefined. The problem is tracked as a GitHub issue #1257. I recommend you to subscribe to the issue to see when it gets resolved or consider contributing a solution.
I'm writing an Open API 3.0 spec and trying to get response links to render in Swagger UI v 3.18.3.
Example:
openapi: 3.0.0
info:
title: Test
version: '1.0'
tags:
- name: Artifacts
paths:
/artifacts:
post:
tags:
- Artifacts
operationId: createArtifact
requestBody:
content:
application/octet-stream:
schema:
type: string
format: binary
responses:
201:
description: create
headers:
Location:
schema:
type: string
format: uri
example: /artifacts/100
content:
application/json:
schema:
type: object
properties:
artifactId:
type: integer
format: int64
links:
Read Artifact:
operationId: getArtifact
parameters:
artifact-id: '$response.body#/artifactId'
/artifacts/{artifact-id}:
parameters:
- name: artifact-id
in: path
required: true
schema:
type: integer
format: int64
get:
tags:
- Artifacts
operationId: getArtifact
responses:
200:
description: read
content:
application/octet-stream:
schema:
type: string
format: binary
renders a link like this:
Is this expected? I ask because the operationId is exposed on the UI and parameters is shown as a JSON reference make it seem like something is not displaying properly. I would have expected a hyperlink or something to take me to the appropriate section in the Swagger web page that corresponds to the API being referenced by the link.
Yes this is how Swagger UI currently renders OAS3 links. Rendering of links is one of the things on their OAS3 support backlog:
OAS 3.0 Support Backlog
This is a collection ticket for OAS3 specification features that are not yet supported by Swagger-UI.
...
[ ] Links can't be used to stage another operation
[ ] Link-level servers are not available for executing requests
The following YAML:
openapi: 3.0.0
info:
title: test
version: 1.0.0
paths:
/test:
get:
summary: test
responses:
'200':
description: Test
content:
application/json:
schema:
oneOf:
- allOf:
- type: object
properties:
firstA:
type: string
- type: object
properties:
firstB:
type: string
- allOf:
- type: object
properties:
secondA:
type: string
- type: object
properties:
secondB:
type: string
Does not render at all in the swagger editor.
In ReDoc it also fails to render properly:
If nesting multiple allOf instances directly inside of oneOf is invalid, how could I achieve the same result with a valid spec?
ReDoc author here.
It is a ReDoc bug. Your spec is valid.
It has been already fixed and will be available in 2.0.0-alpha.40.
My Goal:
I am working on a set of endpoints in an application and I have a swagger 2.0 file with all of the endpoints. They are working on our test environment, but we will not yet make them available in prod.
My question is:
If I upgrade to OpenApi 3, is it possible to hide the paths I don't want to be visible in prod via the servers object?
I didn't think it was from reading the docs, but I would love to be wrong there because I'd prefer to have just one api.yml instead of one for each environment.
Thank you!
I did some testing and the answer is no.
You CAN chose which servers users can run a "try it out" test. Which is a great feature
But, you can NOT hide an endpoint based on which server is chosen from the dropdown at the top of the page. Which was the original goal
Below is the OpenAPI yaml I used in an online editor to verify. I used the online editor here: Swagger Editor and used the petstore.yaml example provided at the OpenAPI-Specification github repo as a starting point. I removed all but one endpoint to shorten things. If you are starting an open api document I would recommend visiting OpenAPI or Swagger to find documentation and a full example.
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
description: Try to not show get when prod server is chosen
license:
name: MIT
servers:
- url: http://prod
- url: http://test
- url: http://dev
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
format: int32
servers:
- url: http://test
- url: http://dev
responses:
200:
description: An paged array of pets
headers:
x-next:
description: A link to the next page of responses
schema:
type: string
content:
application/json:
schema:
$ref: "#/components/schemas/Pets"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Pet:
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
Pets:
type: array
items:
$ref: "#/components/schemas/Pet"
Error:
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
I am having problem with my OpenAPI spec file. I am trying to call an exposed url to 'GET' an id but every time i port forward the service to my local and then try to send request through API document my connection is refused. I would appreciate any help. The id that i am expecting would be in JSON format. Below is my spec file
openapi: "3.0.0"
info:
version: 1.0.0
title: Id Generator
servers:
url: www.someurl.com
paths:
/posts:
get:
summary: Get Id
operationId: id
tags:
- posts
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: "#/definition/Post"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/definition/Error"
definition:
Post:
type: object
properties:
id:
type: string
Error:
properties:
id:
type: string
As of June 21 2017, OpenAPI Specification 3.0 is not out yet and Swagger UI does not support OpenAPI 3.0 yet, so your example can't possibly work. Keep an eye on Swagger UI releases page to know when support for OpenAPI 3.0 is available.
Also, you'll need to fix the errors in your spec to make it a valid OpenAPI 3.0 spec:
servers is an array, so change that to:
servers:
- url: http://www.someurl.com
Response status codes must be quoted: "200" or '200'.
Indent the $ref under schemas:
schema:
$ref: "#/definition/Post"
...
schema:
$ref: "#/definition/Error"
Change definition to components->schemas and fix the indentation for Post:
components:
schemas:
Post:
type: object
properties:
id:
type: string
Error:
properties:
id:
type: string