OpenAPI Spec Connection Refused - swagger

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

Related

Does response status code make sense for multiple media types for error status codes as per OpenAPI 3 (Swagger) spec

If we follow the OAS3 spec for Response here we can see that each response status code can have multiple media types and each media type in turn has a schema particular to it.
UseCase : For example oas3 example below, we can see 200 has a binary stream response but 400 has 3 media-types:application/json, application/xml, text/plain.
So is the client expected to request accept-type header with all the media-types mentioned below. How can we have specific media-type for 400 response code, or basically how we can convey to the REST Service to respond with media type as application/xml when its a 400 bad request and if 200 is returning a binary stream.
Does this OAS3 response multiple media-type make sense for Client/Server Errors. If yes then whats the accept-type set for expecting, say "application/xml" for 400 bad request.
Please refer the below swagger UI snap. Where we see a drop-down for the media-types for error code as well. But when we try out executing the rest operations, the accept header is only populated as per the 200 status code's media-type
openapi: 3.0.0
info:
version: "1.0"
title: Resource
description: Resource service
paths:
/resource:
get:
summary: getResource
description: getResource
operationId: get-resource
responses:
"200":
description: a binary document to be returned
content:
application/octet-stream:
schema:
type: string
format: binary
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/Error400Element"
application/xml:
schema:
$ref: "#/components/schemas/Error400Element"
text/plain:
schema:
$ref: "#/components/schemas/Error400Element"
"500":
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error500Element"
application/xml:
schema:
$ref: "#/components/schemas/Error500Element"
text/plain:
schema:
$ref: "#/components/schemas/Error500Element"
servers:
- url: http://localhost:8088/
components:
schemas:
Error400Element:
type: object
required:
- name
properties:
name:
type: string
number:
type: integer
Error500Element:
type: object
properties:
number:
type: integer
flag:
type: boolean
EDIT : modified the OAS3 spec and the SwaggerUI

How to provide separate examples for each HTTP status code?

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.

Swagger/open api 3.0 links not rendered properly [duplicate]

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

Is it possible to create environment specific paths in OpenApi 3?

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

Swagger/OpenAPI 3.0 issue with example on responses

This is a simplified version of my OpenAPI 3.0 definition I'm viewing on the Swagger Editor online. I am trying to have the two responses for error codes 401 and 403, that share the same schema, show different examples - this doesn't seem to work and I still see the referenced type as example.
Can you help me figuring out what's wrong with the definitions?
openapi: 3.0.0
info:
version: '1.0'
title: A service
paths:
/doSomething:
post:
requestBody:
content:
application/json:
schema:
type: string
example: A string
responses:
401:
$ref: '#/components/responses/Unauthorized'
403:
$ref: '#/components/responses/Denied'
components:
responses:
Unauthorized:
description: The endpoint cannot be reached because the request is not authorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: unauthorized
Denied:
description: The request's authorizations don't match the required ones needed to access the resource
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: permissions denied
schemas:
Error:
type: object
properties:
error:
type: string
Your definition is correct, and the response example show up in Swagger Editor 3.6.5+ and Swagger UI 3.17.4+. Also, multiple examples are supported in Swagger UI 3.23.0+ and Editor 3.6.31+.
I am not sure whether this is at the heart of your problem but I noticed that the HTTP status codes in your path respone sections aren't given enclosed in quotation marks. The OpenAPI specification v3.x (in contrast to v2.x) makes this mandatory which you might want to look up here:
https://swagger.io/specification/#responses-object
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#responses-object

Resources