I have the following versions:
fastify (3.20.1) and fastify-swagger(4.8.4)
I am using fastify in a Node js/JavaScript environment.
Now in my route.js, while I am specifying the fastify.route -- I am writing these two additional tags (after the response: section):
"x-doc": {
title: 'foo1',
category: 'NSS',
filename: 'bar1',
},
"my-custom-tag": {
title: 'foo2',
category: 'NSS',
filename: 'bar2',
},
Result:
However in the generated JSON (swagger.json or swagger.yaml), I can see the x-doc is appearing, but not the my-custom-tag.
Of course, as I did not using custom swagger-ui, I did not expect none of these stuffs (x-doc or my-custom-tag) to appear in the swagger html, while viewing from browser.
However I would like to know the reason behind partcularly x-doc to appear in resultant JSON, but not my-custom-tag.
And what I need to do if I want to make my-custom-tag also appears in resultant JSON/yaml?
As per comment from #Helen above, putting a "x-" makes the difference.
In swagger specification:
'x-doc': {
field1: 'property1',
field2: 'property2',
field3: 'property3',
},
'x-my-custom-tag': {
field1: 'property1_custom',
field2: 'property2_custom',
field3: 'property3_custom',
}
Generated JSON.
Related
I've been struggling with an issue in an openapi 3.0.1 spec json document I've been working on.
The issue I'm seeing in the online swagger editor (editor.swagger.io) is very strange where the Request body Example Value section of a POST does not show the "layers", which is an array defined within my MixBase schema component, based on the MixLayer schema component. The MixLayer schema component has an array of MixLayerComponent schema components.
However, if I include a $ref to the MixBase schema in the responses section, all the elements are shown correctly.
Request body Example Value section that is missing the 'layers':
{
"mixId": "4f8b533f-7449-4056-92ff-11b1de94d656",
"mixDescription": "SES5M",
"mixScaleName": "MyScale",
"mixRoom": "MixingRoomABC",
"mixProgramId": "ABC-123-ProgramId",
"mixDateTime": "2018-06-07T12:51:25.077Z",
"mixState": "Paused",
"mixNumber": "131",
"mixedByUserName": "john.smith#example.com",
"mixedByFirstName": "John",
"mixedByLastName": "Smith"
}
Responses Example Value section returning the correct list of elements including 'layers':
{
"mixId": "4f8b533f-7449-4056-92ff-11b1de94d656",
"mixDescription": "SES5M",
"mixScaleName": "MyScale",
"mixRoom": "MixingRoomABC",
"mixProgramId": "ABC-123-ProgramId",
"mixDateTime": "2018-06-07T12:51:25.077Z",
"mixState": "Paused",
"mixNumber": "131",
"mixedByUserName": "john.smith#example.com",
"mixedByFirstName": "John",
"mixedByLastName": "Smith",
"layers": [ -- this represents the MixLayer component
{
"unitOfMeasure": "g",
"Components": [ -- this represents the MixLayerComponent correctly
{
"code": "800C",
"description": "800C",
"poured": 204.5,
"density": 1.041
}
]
}
]
}
My requestBody section is defined as: (doesn't show 'layers')
requestBody:
required: true
description: Paint mix information to create
content:
application/json:
schema:
$ref: '#/components/schemas/MixBase'
My responses section is defined as: (and this displays correctly in the Response examples section)
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/MixBase'
Here is the definition of the 'layers' within the MixBase schema component (which is the last element in the MixBase definition which is why additionalProperties is set to false): (The formatting might not be correct in stack overflow but the swagger editor doesn't complain so I don't believe the issue is linked to formatting)
layers:
description: Layer related information for components of the mix
type: array
items:
$ref: '#/components/schemas/MixLayer'
readOnly: true
additionalProperties: false
Here is the definition of the MixLayer:
MixLayer:
required:
- Components
type: object
properties:
unitOfMeasure:
description: Unit of volume for the components of the layer
maxLength: 10
type: string
nullable: true
example: g
Components:
description: The components that make up the layer in the mix
type: array
items:
$ref: '#/components/schemas/MixLayerComponent'
readOnly: true
additionalProperties: false
Here is the definition of the MixLayerComponent:
MixLayerComponent:
required:
- code
- density
- poured
type: object
properties:
code:
description: The code associated with the mix component of the layer
maxLength: 25
minLength: 1
type: string
example: 800C
description:
description: The description of the mix component of the layer
maxLength: 120
type: string
nullable: true
example: 800C
poured:
description: >-
The quantity, expressed in the unit of measurement, consumed for the
mix component
type: number
format: double
example: 204.5
density:
description: The density associated with the mix component of the layer
type: number
format: double
example: 1.041
additionalProperties: false
I thought that the "Components" element in the MixLayer component schema might be a reserved keyword in openapi so I changed the references to something else and it still has the same issue.
I thought this issue might be with the online swagger editor (editor.swagger.io) but the same thing occurs in Postman. I also tried browsers Chrome, Edge, and Firefox and they all
have the same issue. I have also tried an XML content type in addition to the JSON I would like to use but still the same issue.
I don't access to post my openapi.json file on stack overflow but I hope this provides enough information.
Any insights anyone has for me to continue a line of investigation would be greatly appreciated.
Thank you for your time in advance,
Dave
layers is defined as a read-only property (readOnly: true) - that's why it doesn't appear in the request body example.
While using swagger-editor I create the below YAML that shows an example of the response object. It's properly displaying in the swagger-editor. When I then download the JSON and display it in swagger-ui, the example is completely missing.
/person/{email}/create:
post:
summary: Create a new account
tags:
- Person
parameters:
...
responses:
201:
description: The new SQL ident and sport details
examples:
application/json: |
[
12,
[
{
"sql_idnet" : 12,
"name" : "Basketball"
},
{
"sql_ident" : 13,
"name" : "Ice Hockey"
}
]
]
This might be because the response does not have a schema - in Swagger this means the response does not have a body.
That said, Swagger UI 3.0 displays this example correctly.
Swagger UI and Swagger Editor currently do not support multiple examples. You can follow this issue for updates.
I'm working on an API definition in Swagger Editor with YAML. I am trying to represent the following response body:
{
success: true,
ids: [123456, ...]
}
and this is what my YAML looks like:
definitions:
SuccessfulResponse:
type: object
properties:
success:
type: boolean
description: True if the all operations were successful
ids:
type: array
items:
id:
type: string
Ive tried several different ways but like this but nothing seems valid
How do I properly describe the return object that Ive given above?
Here is an example to define a property as an array of string:
photoUrls:
type: array
items:
type: string
Ref: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml#L661-L667
I defined a GraphQL Mutation using graphql-relay but am having issues figuring out how to submit a mutation to it.
Here is the relevant schema:
const userType = new GraphQLObjectType({
name: 'User',
description: 'user',
fields: () => ({
id: {
type: new GraphQLNonNull(GraphQLString),
description: 'The UUID for the user.',
resolve(user) {
return user.uuid;
},
},
})
});
const registerUser = mutationWithClientMutationId({
name: 'registerUser',
inputFields: {
},
outputFields: {
user: {
type: userType,
resolve: (payload) => {
models.user.findById(payload.userId);
}
},
},
mutateAndGetPayload: (args) => {
var newUser = models.user.build().save();
return {
userId: newUser.id,
};
}
});
const rootMutation = new GraphQLObjectType({
name: 'RootMutationType',
fields: {
registerUser: registerUser,
},
});
const schema = new GraphQLSchema({
query: rootQuery,
mutation: rootMutation,
});
What should an HTTP call look like to register a new user and get back the userId?
Thanks!
I want to point out that I see that you're saying that your mutation requires no parameters - how does it know what the new user's details are? You'll probably need some parameters on that mutation, eventually. They would be available to your mutateAndGetPayload on that first function parameter. (I'm not saying every mutation needs parameters, but this one probably does)
If you're using Relay, there is some pretty good information on the official document as to how to use your mutations from Relay. Particularly down at the bottom where it shows the various mutator configs. If you're using connections, you may want to use RANGE_ADD to add this new account to the Relay store manually, otherwise if you'd like to perform a more broad refetch you can use FIELDS_CHANGE. You said you need the new user id after the mutation finishes. If you're using Relay, you may need to look into REQUIRED_CHILDREN to specify that regardless of the computed query that Relay will build, you always want that id to be queried.
The output of your mutation is a userType, so you'd be able to access it with a fragment on the payload type, which would probably be RegisterUserPayload, that might look something like ...
fragment on RegisterUserPayload {
user {
id
}
}
Now, that's assuming you're using Relay. If you'd like to try this out manually via GraphiQL, then you can use the examples of how to do mutations through there on the GraphQL Mutation docs. There's a direct example of how you'd query your mutation.
Last, since you asked how to do this at a low level of issuing the HTTP request yourself, for that you can look at express-graphql documentation, which explains how to query it.
I figured out a mutation format that worked:
mutation RootMutationType {
registerUser(input:{clientMutationId:"123"}){
clientMutationId, user { id }
}
}
I'm using RoR for a couple of time. But after read many json specification for example jsonapi.org and json-schema.org I have the next question: What is the default JSON specification used in RoR ?
Because when you render a json in RoR you get this for example:
post: {
id: 1,
title: 'Stackoverflow rised 1 billion of alien money',
description: 'blablabla'
}
Is it a good practice if I used the default response in RoR when I'm creating an API ?
One specific thing that may or may not be helpful...
One thing that bothers me about the default rendering of JSON w/ Rails is that it leaves the key names unquoted when serializing a Hash, which is (technically) not valid JSON. The way to fix this is to add
ActiveSupport::JSON.unquote_hash_key_identifiers = false
to a configuration file like environment.rb. Once you've done that, serializing
my_hash = { post: { id: 1, title: 'Stackoverflow rised 1 billion of alien money', description: 'blablabla' } }
to JSON would change to
post: {
"id": 1,
"title": 'Stackoverflow rised 1 billion of alien money',
"description": 'blablabla'
}
vs. what you have above without the quotes.