YAML Syntax Error: Incomplete explicit mapping pair; a key node is missed at - api

I'm writing swagger spec in YAML and getting vague errors. I've mapped my paths and definitions I think correctly, and not sure what this error means:
YAML Syntax Error Incomplete explicit mapping pair; a key node is
missed at line 66, column 30: format: int64schema: ^t
Lines:
Line 65: type: integer
Line 66: format: int64
Swagger:
/product/{productId}:
get:
tags:
- content
summary: Find product item by ID
description: Returns a product item when ID < 10. ID > 10 or nonintegers will simulate API error conditions
operationId: getProductItemByID
produces:
- application/json
- application/xml
parameters:
- in: path
name: productId
description: ID of menu item that needs to be fetched
required: true
type: integer
format: int64
schema:
$ref: "#/definitions/Product"
responses:
"404":
description: Product item not found
"200":
description: successful operation
schema:
$ref: "#/definitions/Product"
"400":
description: Invalid ID supplied
security:
- api_key: []
- my_auth:
- write
- read
Then at bottom of swagger file in definitions:
definitions:
Product:
type: object
properties:
id:
type: integer
format: int64
category:
$ref: '#/definitions/Category'
name:
type: string
detail:
type: string

From swagger 2.0 spec, if 'in' parameter is a "path" you can't use a schema.
I think there is a mistake and you should use :
/product/{productId}:
get:
tags:
- content
summary: Find product item by ID
description: Returns a product item when ID < 10. ID > 10 or nonintegers will simulate API error conditions
operationId: getProductItemByID
produces:
- application/json
- application/xml
parameters:
- in: path
name: productId
description: ID of menu item that needs to be fetched
required: true
type: integer
format: int64
responses:
"404":
description: Product item not found
"200":
description: successful operation
schema:
$ref: "#/definitions/Product"
"400":
description: Invalid ID supplied
...

Related

In OAS3.0, Can you set the required fields in a request body of fields in a "oneOf" or "anyOf"

This question relates to Open API spec 3 and writing API specifications.
I have been trying to work out how to set fields as required for a specific method requestBody when I am using a "oneOf" in a schema object.
I know how to set required fields of a referenced object, but when you try set the required properties of oneOf objects the same way, it does not work.
I also know that I can set the required fields in the schema object itself, however I do not want to do this as the required fields differ on each method (i.e all fields required for a post, but only some required for a patch).
So essentially, how do I set the required fields in a request body of a schema used in oneOf?
I have created an example below, in it, I want to:
Set the fields Bird - wingSpan and beakLength as required in the Post method
Set the fields Cat - tailLength as required in the Post method
Not have any required fields for Bird and Cat in the Patch method.
openapi: 3.0.3
servers:
- description: SwaggerHub API Auto Mocking
url: https://virtserver.swaggerhub.com/Enable-Networks/TroubleTicket/1.0.0
info:
title: Pet API
version: 1.0.0
paths:
/pet:
patch:
summary: Update a pet
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/Pet"
- type: object
required:
- age
responses:
"204":
description: The request was a success and the pet was successfully created.
post:
summary: Create a pet
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/Pet"
- type: object
required:
- name
- age
- species
properties:
species:
type: object
required:
- ???
responses:
"204":
description: The request was a success and the pet was successfully created.
components:
schemas:
Cat:
type: object
properties:
tailLength:
type: integer
whiskerLength:
type: integer
Bird:
type: object
properties:
wingSpan:
type: integer
beakLength:
type: integer
highestAltitude:
type: integer
Pet:
type: object
properties:
name:
type: string
age:
type: string
species:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Bird'
Any help on this would be appreciated!
I have read the documentation 10x, tried everything from discriminators to not using refs.
I have tried many different combinations of the below and still nothing works.
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/Pet"
- type: object
required:
- name
- age
- species
properties:
species:
type: object
required:
- ???

POST in openapi

I'm new in the world of API. I want to do an API using swagger in yaml. My teacher given us a snippet of code that should simulate a login API, but Bearer style. I want to map the generated identifier with the correlated name
paths:
/session:
post:
tags: ["login"]
summary: Logs in the user
description: |-
If the user does not exist, it will be created,
and an identifier is returned.
If the user exists, the user identifier is returned.
operationId: doLogin
requestBody:
description: User details
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: Jason
pattern: 'ˆ.*?$'
minLength: 3
maxLength: 16
required: true
responses:
'201':
description: User log-in action successfully
content:
application/json:
schema:
type: object
properties:
identifier:
# change here if you decide to use an integer
# or any other type of identifier
type: string
example: "abcdef012345"
/session/{identifier}:
get:
summary: Get username
description: Get username from identifier
operationId: getUsername
parameters:
- name: identifier
in: path
description: User ID
required: true
schema:
$ref: "#/components/schemas/User/properties/identifier"
responses:
'200':
description: 'User exists'
content:
application/json:
schema:
$ref: "#/components/schemas/User"
components:
schemas:
User:
type: object
properties:
identifier:
type: string
example: "abcdef012345"
name:
type: string
example: "Jason"
I tried adding the "/session/{identifier}" path, but the get never retrieve the correct information. How can I do it?
Thank you in advance

Customising a Components object - OpenAPI

Is it possible to assign a customised name to a Components object in OpenAPI?
I currently have two Component objects that specify a request schema:
Request1:
type: object
description: Request 1
properties:
a:
description: Filter 1 a
$ref: '#/definitions/Filter1a'
b:
description: Filter 1 b.
$ref: '#/definitions/Filter1b'
Request2:
type: object
description: Request 2
properties:
query:
type: object
description: Filter 2.
properties:
bool:
type: object
properties:
must:
type: array
items:
type: object
properties:
match_all:
type: object
In the endpoint description I refer to these schemas as follows:
/v2/myEndpoint:
post:
tags:
- some tags
operationId: someId
summary: Some summary
description: Some description
produces:
- application/json
parameters:
- in: body
name: body
required: false
schema:
oneOf:
- $ref: '#/definitions/Request1'
- $ref: '#/definitions/Request2'
When I publish the yaml file, the UI shows Request1 and Request2 in selection tabs, which carry the names 'Request1' and 'Request2'. Is it possible to assign custom names to them, so that the UI will show the custom names instead? For example 'Custom name request 1' and 'Custom name request 2'?
Many thanks!
I assume you meant Swagger UI.
title would do that. Link to Open Api Spec.
Request1:
title: Custom name request 1
type:...
Request2:
title: Custom name request 2
type:...

Does a POST method create a new entity, and return the id of that entity, in openapi 3.0.2?

I understand that a POST method in openapi 3.0.2 is supposed to create a new entity, and return the id of that entity. When I add an additional route to GET or DELETE that entity by ID, I get a 404 error. I don't quite know why that might be.
Here are my post and get methods:
/api/globalorderdays:
post:
tags:
- Setup Global Order Days
summary: Allows user to add order days and holidays to multiple
sessions.
requestBody:
required: true
description: put text here
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalOrderSetupInfo'
responses:
201:
description: Created
400:
description: Bad request
401:
description: Unauthorized
/api/globalorderdays/{Id}:
get:
tags:
- Setup Global Order Days
summary: put text here
parameters:
- in: path
name: Id
required: true
description: put text here
schema:
type: integer
example:
responses:
200:
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalOrderSetupInfo'
400:
description: Bad request
401:
description: Unauthorized
/api/globalorderdays/{Id}:
delete:
tags:
- Setup Global Order Days
summary: Allows user to delete added order days
parameters:
- in: path
name: Id
required: true
description: put text here
schema:
type: integer
example:
responses:
204:
description: Deleted
400:
description: Bad request
401:
description: Unauthorized
Here are the components:
GlobalOrderSetupInfo:
description: 'Put Text Here'
type: object
properties:
Id:
type: integer
nullable: true
AvailableHolidayList:
type: string
nullable: true
SelectedOrderHolidays:
type: string
nullable: true
SelectedHolidays:
type: string
nullable: true
OrderDays:
type: string
nullable: true
NoOrderDays:
type: string
nullable: true
AllSessionList:
uniqueItems: false
type: array
items:
$ref: '#/components/schemas/SessionInfoList'
SessionIdString:
type: string
nullable: true
SessionInfoList:
description: 'Put Text Here'
type: object
properties:
Id:
type: integer
nullable: true
SessionID:
type: integer
nullable: true
Name:
type: string
nullable: true
Type:
type: string
GroupName:
type: string
IsChecked:
type: boolean
default: false
SetupID:
type: string
nullable: true
I expect to be able to retrieve/delete the entity by Id, but I return 404 errors
There are several issues with your spec.
The /api/globalorderdays/{Id} path is repeated several times. This is not valid.
# Incorrect
/api/globalorderdays/{Id}:
get:
...
/api/globalorderdays/{Id}:
delete:
...
Instead, specify the path once and list all of its HTTP methods below it, like so:
/api/globalorderdays/{Id}:
get:
...
delete:
...
Parameter examples are missing the value:
schema:
type: integer
example: # <-----
A missing value in YAML is an equivalent of null, but null is not a valid example for an integer schema. Either add a proper integer example, such as example: 1, or remove the example keyword from those schemas.
Once these issues are fixed, the mocks for GET and DELETE will work properly.

How can I declare the response array type for OpenAPI definition with JAX-RS?

I'm building a REST service with JAX-RS, Microprofile and Payara 5. My method returns an object of type Response. The response itself contains a List of MyClass. The implementation looks like this:
import org.eclipse.microprofile.openapi.annotations.enums.SchemaType;
import org.eclipse.microprofile.openapi.annotations.media.Content;
import org.eclipse.microprofile.openapi.annotations.media.Schema;
import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
#GET
#Path("/{a}/{b}/{c}")
#APIResponse(content = #Content(schema = #Schema(type = SchemaType.ARRAY, implementation = MyClass.class)))
public Response getMyClass(#PathParam("a") String a,
#PathParam("b") String b,
#PathParam("c") String c) {
return Response
.ok()
.entity(new ArrayList<>())
.build();
}
The generated OpenAPI definition looks like this:
/api/translations/{a}/{b}/{c}:
get:
operationId: getMyClass
parameters:
- name: a
in: path
required: true
style: simple
schema:
type: string
- [...]
responses:
default:
description: Default Response.
content:
'*/*':
schema:
type: array
items: {}
As you can see, the definition of MyClass.class is missing in the response type. How can I add that type to the definition? Is the #ApiResponse annotation the correct way to achieve this?
I tested this today with the newest payara 5.191 and it did not worked for me too.
It seems that there is a bug in the current payara implementation, because I checked the example on this page guide-microprofile-openapi
The same implementation has 2 different openapi generations (Payara and OpenLiberty)
Payara:
openapi: 3.0.0
info:
title: Deployed Resources
version: 1.0.0
servers:
- url: https://10.0.0.72:8080/ipma
description: Default Server.
paths:
/resources/server:
get:
summary: List servers.
description: 'Returns all servers '
operationId: getServers
responses:
default:
description: Special description
content:
application/json:
schema:
type: array
/resources/server/{id}:
get:
summary: get server by id.
description: 'return one server with the specified id'
operationId: getServerById
parameters:
- name: id
in: query
style: simple
schema:
type: number
responses:
default:
description: Special description
content:
application/json:
schema:
$ref: '#/components/schemas/Server'
components:
schemas:
Server:
properties:
name:
type: string
example: test
id:
type: number
example: "0"
description: foo
OpenLiberty:
openapi: 3.0.0
info:
title: Deployed APIs
version: 1.0.0
servers:
- url: http://localhost:9080
paths:
/resources/server/{id}:
get:
summary: get server by id.
description: 'return one server with the specified id'
operationId: getServerById
parameters:
- name: id
in: query
schema:
type: integer
format: int64
responses:
default:
description: Special description
content:
application/json:
schema:
$ref: '#/components/schemas/Server'
/resources/server:
get:
summary: List servers.
description: 'Returns all servers '
operationId: getServers
responses:
default:
description: Special description
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Server'
components:
schemas:
Server:
required:
- id
- name
type: object
properties:
id:
type: integer
format: int64
example: 0
name:
type: string
example: test
description: foo