Paw has good tools for documenting simple APIs, but now I need to do something more complicated and I would like to use JSON Schema references.
For example, like the following snippet from the Swagger 2.0 examples, where the definitions are presented later in the document:
"post": {
"description": "Creates a new pet in the store. Duplicates are allowed",
"operationId": "addPet",
"parameters": [
{
"name": "pet",
"in": "body",
"description": "Pet to add to the store",
"required": true,
"schema": {
"$ref": "#/definitions/NewPet"
}
}
],
...
Is there a way to to this in Paw?
Related
Is there a mechanism in Swashbuckle that can prevent definitions from being created with referencing to them in parameters/responses/etc.?
By default, you might get a path that looks like this:
"/profile": {
"get": {
"summary": "Get my profile details.",
"produces": [
"application/json",
],
"parameters": [],
"responses": {
"200": {
"description": "Success",
"schema": {
"$ref": "#/definitions/ProfileModel"
}
}
}
}
}
But what I'd like is for it to expand the schema inline like this:
"/profile": {
"get": {
"summary": "Get my profile details.",
"produces": [
"application/json",
],
"parameters": [],
"responses": {
"200": {
"description": "Success",
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "id"
},
"firstName": {
"type": "string",
"description": "firstName"
},
"surname": {
"type": "string",
"description": "surname"
},
"emailAddress": {
"type": "string",
"description": "emailAddress"
}
}
}
}
}
}
}
I reviewed this StackOverflow question and I don't think it's what I'm looking for (or maybe misinterpreted).
Taken a look through the Swashbuckle README to understand its capabilities but coming up short. Any help here would be most appreciated.
For additional context, looking at the Swashbuckle PDF documentation in section 1.7, I essentially want to bypass or revert the action they describe as
automatically generating a corresponding schema for user-defined reference types and reference the definition via the $ref keyword.
Digging into the codebase a little, it looks like it's not possible at the moment.
However, you can create a custom ISchemaGenerator from the one in source and alter the GenerateConcreteSchema method under the DataType.Object case to not return as reference and this solves the issue.
Is it a violation of the JSON-API spec to allow reverse relationships to be created automatically?
I need to create resources that, when I link A to B in a relationship, automatically links B to A. In this way I can traverse A to find all of its Bs and can find the parent A from a B. However, I don't want to POST/PATCH to 2 relationships to get this right. I want to establish the relationship once.
Now I know that it is an implementation detail as to how the server maintains link/references as well as how the behaviour is established but I want to build the API in such a way that it doesn't violate the spec.
Assuming I have resources Books and Authors. Books have Authors and Authors have Books. The question is, once I relate an Author to a Book, I need the reverse relationship to be created as well. Is it a violation of the spec in any way to assume that this reverse relationship can be automatically created by simply doing one POST to the Books resource's relationship?
By way of example, starting with the book.
{
"data": {
"type": "books", "id": 123, "attributes": ...,
"links": { "self": "/books/123" },
"relationships": {
"self": "/books/123/relationships/authors",
"related": "/books/123/authors"
}
}
}
And the author
{
"data": {
"type": "authors", "id": 456, "attributes": ...,
"links": { "self": "/authors/456" },
"relationships": {
"self": "/authors/456/relationships/books",
"related": "/authors/456/books"
}
}
}
If I establish the link from a book to an author with a POST to /books/123/relationships/authors
{
"data": [{ "data": "authors", "id": "456" }]
}
Do I need to explicitly do the same for the Author 456 as a POST to /authors/456/relationships/books?
{
"data": [{ "data": "books", "id": "123" }]
}
Or can I let the server build the relationship for me so that I can avoid the second POST and just see the automatic reverse relationship at GET /authors/456/relationships/books?
From the perspective of the spec this is only one relationship represented from two different sides. author and book have a many-to-many relationship. This relationship could be represented in author's resource object as well as book's resource object and of course also via there relationship links. Actually it would be a violation of the spirit of the specification if representations wouldn't match. Having one-sided relationships is another story but in that case one side wouldn't know about the relationships at all (e.g. a book is associated with an author but the author model does not know which books are associated with it).
A post to either one side of that relationship creates the relationship between the two records. It shouldn't matter which side is used to create that relationship and if it's created as part of a creation / update to a resource via it's resource object or via a relationship link representing that relationship. The same applies to deletion of that relationship.
Maybe an example would make that even more clear. Let's assume a book is created with a POST to /books?include=author having these payload:
{
"data": {
"type": "books",
"relationships": {
"author": {
"data": {
"type": "authors",
"id": "1"
}
}
}
}
}
The response may look like this:
{
"data": {
"type": "books",
"id": "7",
"relationships": {
"author": {
"data": { "type": "authors", "id": "1" }
}
}
},
"included": [
{
"type": "authors",
"id": "1",
"relationships": {
"books": {
"data": [
{ "type": "books", "id": "7" }
]
}
}
}
]
}
I want to have access to the definitions in the schema in order to get the naming of the definition. I am using newtonsoft.json v11.01
I am building a c# converter for jsonschema to make a syntaxtree and compile it in order to get a typed version of the object at runtime.
{
"$id": "https://example.com/arrays.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "xml remarks",
"type": "object",
"properties": {
"fruits": {
"type": "array",
"items": {
"type": "object",
"title": "fruit",
"required": ["naam"],
"properties": {
"naam": {
"type": "string",
"description": "The name of the fruit."
}
}
}
},
"vegetables": {
"type": "array",
"items": { "$ref": "#/definitions/veggie" }
}
},
"definitions": {
"veggie": {
"type": "object",
"required": [ "veggieName", "veggieLike" ],
"properties": {
"veggieName": {
"type": "string",
"description": "The name of the vegetable."
},
"veggieLike": {
"type": "boolean",
"description": "Do I like this vegetable?"
}
}
}
}
}
in the schema a reference is created with the name veggie. This is used in the property vegetable with a reference.
Json schema contains a definition on the root object but is doesn't have it on the property element. On the property element there is nothing identifiable to point to the right definition.
how do i find the right definition for the property?
In general, in order to resolve a json-pointer (a $ref is a "uri-reference", and the part after the # is a "json-pointer"), you need to have access to the root of the json document.
So if you currently have a function that only gets an argument that points to the "properties" section, then you need to give that function a second argument that points to the root of the document.
(It gets more complicated when you're using a schema made up of more than one file; then you need a second argument that points to the roots of all the schema documents)
It's one of the more difficult parts of writing software that interprets json-schema files, especially if your language/library doesn't have support for json-pointers built-in - you'll need to write it yourself in that case.
First of all I want to implement JSON API.
I follow tutorial on api platform and just like in example create entities and response is like
{
"links": {
"self": "/api/books"
},
"meta": {
"totalItems": 1,
"itemsPerPage": 30,
"currentPage": 1
},
"data": [
{
"id": "/api/books/1",
"type": "Book",
"attributes": {
"isbn": "9781782164104",
"title": "Persistence in PHP with the Doctrine ORM",
"description": "This book is designed for PHP developers and architects who want to modernize their skills through better understanding of Persistence and ORM.",
"author": "Kévin Dunglas",
"publicationDate": "2013-12-01T00:00:00+01:00",
"_id": 1
},
"relationships": {
"reviews": {
"data": [
{
"type": "Review",
"id": "/api/reviews/1"
}
]
}
}
}
]
}
My api_platform.yaml config
api_platform:
mapping:
paths: ['%kernel.project_dir%/src/Entity']
formats:
jsonapi:
mime_types: ['application/vnd.api+json']
So i have problem with id filed in data. I get id fields in format api/entityName/id but I just want to get number(string), just like in JSON API. So is there some configuration that i miss or is any way to achieve that
It was discussed here.
You need to use Normalizer or create custom getter.
All you need is to send
Accept: application/json
on request header.
The pact broker overview page (the index page) displays the verification status of each pact which is very useful. Is it possible to filter this view, by a query parameter or such, so that I can see the verifications for a certain tag? I would like to use this to have an overview of all the prod-tagged pacts and their verifications to make sure that all prod-pacts have been verified when making releases of components.
If not I'm contemplating having a separate pact broker instance for the prod pacts.
Thanks!
It's totally doable. It's just a matter me (or someone else) having the time to do it. I've raised an issue for it here:
https://github.com/pact-foundation/pact_broker/issues/146
In the meantime, you can make your own "dashboard" by making a CI build for each prod tag. I think I may have put this on the gitter channel already.
Call /pacts/provider/PROVIDER/consumer/CONSUMER/latest/prod. Follow the pb:consumer-version relation, then follow the pb:latest-verification-results-where-pacticipant-is-consumer relation.
You'll get this.
{
"success": true,
"providerSummary": {
"successful": [
"B"
],
"failed": [],
"unknown": []
},
"_embedded": {
"verificationResults": [
{
"providerName": "B",
"providerApplicationVersion": "2",
"success": true,
"verificationDate": "2017-10-09T12:34:17+08:00",
"_links": {
"self": {
"title": "Verification result",
"name": "Verification result 2 for Pact between A (v1) and B",
"href": "http://localhost:9292/pacts/provider/B/consumer/A/pact-version/7954fb780aa0db0ea451db4c3c1012fb7f0e1eb4/verification-results/2"
},
"pb:pact-version": {
"title": "Pact",
"name": "Pact between A (v1) and B",
"href": "http://localhost:9292/pacts/provider/B/consumer/A/version/1"
}
}
}
]
},
"_links": {
"self": {
"href": "http://localhost:9292/verification-results/consumer/A/version/1/latest",
"title": "Latest verification results for consumer A version 1"
}
}
}
I'll try and prioritise adding the tagged pacts to the UI.