In OpenAPI Spec 3.0, there is a components section where you can define headers,links, schemas etc and then reuse them for various operations.
components:
# Reusable schemas (data models)
schemas:
...
# Reusable path, query, header and cookie parameters
parameters:
...
# Security scheme definitions (see Authentication)
securitySchemes:
...
# Reusable request bodies
requestBodies:
...
# Reusable responses, such as 401 Unauthorized or 400 Bad Request
responses:
...
# Reusable response headers
headers:
//...
I have a number of headers that are common across various operations so it makes sense, from an open API perspective they are defined in the components section s so they can be re-used.
In Swagger, when you use #Schema it will be end up in components / schema section, but I am struggling to see how you can get a parameter or header into the components section so they can be reused.
(Note: I am using jax-rs / Jersey)
I wrote a YAML that has a header and parameter defined in components / schema an then generated the Java JAX-RS / Jersey from that but it defined the header and parameter for very API Operation. There was no re-use. It was also missing the description for header I had defined in components / header in the YAML.
Looking at the JDoc:
http://docs.swagger.io/swagger-core/v2.0.8/apidocs/index.html?io/swagger/v3/oas/annotations/OpenAPIDefinition.html
It says (for header, that I use the ref attribute to refer to something in the components section, but the question is how do I get it into the components section)
Any help appreciated.
For now, only "schemas" and "securitySchemes can be defined via Java annotations.
Btw, as a workaround, you can define global components in a YAML spec file and merge it with the annotation-driven specs at runtime.
Take a look to this issue of "Swagger" that talks about "components/parameter" section.
issue 3021
and issue 2625
Related
I need to have a "global argument" that can be specified (at most) once and applies to the entire request (having however many queries/mutations inside). If I were able to have the client specify it in query(arg: "value") {...} and/or mutation(arg: "value") {...} I would... but I understand this is reserved for "variables". I dislike other options I am aware of:
HTTP header - ties this to HTTP only, not in schema, not documented nicely.
POST /graphql
X-MyArg: some-value
...
{"query":"{someQuery{id name}}"}
HTTP (URL) query string parameter - ugh... I like the single common URL, also same problems as with (1)
POST /graphql?myArg=some-value
...
{"query":"{someQuery{id name}}"}
Introduce an intermediate wrapper field to expose this argument ... but this makes everything longer and I don't know of a way saying "this must be specified/requested at most once", while supporting multiple occurrences makes no sense for at least some of these (e.g. authentication / authorization / security related and others).
POST /graphql
...
{"query":"{wrapper(arg: \"some-value\"){someQuery{id name}}}"}
Cheat/hack and require an $arg variable (meant to be defined by the API client(s)) to be specified while somehow preventing the framework I am using from throwing up when that variable isn't actually referenced from anywhere inside.
POST /graphql
...
{"query":"query($arg:String){someQuery{id name}}","variables":{"arg":"some-value"}}
Can anyone help? Am I missing something or am I really forced to pick one of those poison pills?
I have a question about the light-rest-4j URL validation, for example, if I have a POST request path /party, if I type the path as /party11, I will get error: No handler defined for path /party11, but if I put /party?qqqq, It will pass through, and system treat it as /party should we add validation for this? Our QA team creates this as a defect, in case user input it by mistake, they expect to have error message return.
The light-rest-4j framework validates the request/response based on the OpenAPI specification during the runtime; however, it only validates based on the spec — nothing more and nothing less. In most cases, the spec will define the type of headers, query parameters, path parameters, and cookies, as well as if they are required. We make sure these are validated as defined. For anything that is not defined in the spec, we are doing nothing. For example, an extra query parameter or an extra header in the request will be ignored as they are not defined in the spec. We cannot do any negative validation as we don't know if any client will add additional headers or query parameters for tracing, auditing, etc. A request that comes from one client might be different than another one comes from the same client through a gateway or proxy.
I have an app written with reason-react using apollo-client. I have defined some fragments on the frontend to basically reuse some field definitions. I'm setting up automated tests for a components that uses fragments, but I keep getting this warning saying I need to use the IntrospectionFragmentMatcher.
'You are using the simple (heuristic) fragment matcher, but your queries contain union or interface types. Apollo Client will not be able to accurately map fragments. To make this error go away, use the `IntrospectionFragmentMatcher` as described in the docs: https://www.apollographql.com/docs/react/advanced/fragments.html#fragment-matcher'
I've tried setting up the fragment matcher according to the docs. The codegen result returns no types:
{
"__schema": {
"types": []
}
}
When I queried my server and looked at the manual method recommended by apollo-client, I noticed it would also return no types.
Another strange thing is that when I don't use the fragment matcher, I get the mocked response back but I just get the warnings from apollo. If I do use it then the mocked response doesn't return correctly.
Why would I query the graphql api for fragments defined in my frontend code? Why would I only received these errors when running the tests & using mock data, but not when running my actual application?
As the error states, the default fragment matcher does not work on intersection or union types. You will need to use Apollo's IntrospectionFragmentMatcher. It works by asking the server (introspecting) for information about your schema types, and then providing that information for reference to the cache so that it can match the fields accurately. It's not querying the server for information about the fragments you are defining on the front end, it's asking for data about the GraphQL schema that must be defined on your back end so that it can properly relate the two. There is an example in the documentation, also more information here.
As for why your server is not returning any types, that is a separate issue that would require more info to debug. If you're using Apollo Server, doublecheck your schema to make sure all the necessary types are defined properly and that you are passing them into the server when it's initialized.
The “model” facility seems intended to reduce duplication — when specifying the requests and responses to various methods on a resource, the same body will frequently be specified multiple times. So one can define a “model” and then “refer” to it within various request and response “payload” sections.
So I’ve defined a model like so:
### An Event
* Model (application/vnd.document+json)
{
"_type": "document",
...
}
and I can then refer to it in various places:
* Response 200
[An Event][]
which works great; the output includes the entire model body in place of the cross-reference.
However, I can’t figure out how to combine this reference with a request or response header.
I’ve tried various formats along these lines:
* Request
* Headers
If-Match: some-etag-value
* Body
[An Event][]
or
* Request
* Headers
If-Match: some-etag-value
[An Event][]
with no luck.
Is there any way to do this?
There is currently no way to alter referenced model's payload. Neither it's planned in any of API Blueprint Milestones.
Feel free to add it to the milestones and propose its syntax, if you will. Before doing so please consider any potential synergy with planned API Blueprint Object Traits.
I want to build a typical mvc app for CRUD of simple items, the api s should be RESTful. The catch here is, that i have a large pallete of items that needs to be initialized. On the server side those items are defined as java beans and the corresponding create form for the item is dynamically created from the field information(data type, validation constraints etc) harvested from the bean.
I am new to REST and just read up about how the urls should be nouns defining the resource and action specified by HTTP verb. In that perspective how to model something like
.../client/showForm?type=xyz from non RESTful way to RESTful one ?? My intention here is to tell the server to dynamically construct and send back a CREATE form for client of type xyz. The obvious problem with url i mentioned above is that it specifies action in the url which, from what i have read, makes it non RESTful.
When I think of REST, I think of resources. I think of data. In other words, I don't think of REST as being something that I would typically use to retrieve a form, which is a user interface component.
REST is an architectural style that is used to identify a resource on a server using a uniform resource identifier, or URI. Additionally, actions performed on those resources identified by the URI are determined based on the specific HTTP Method used in the request: GET, POST, PUT, DELETE, etc.
Thus, let's say you have a Client object. That client object might have the following properties:
Name
Location
AccountNumber
If I wanted to retrieve the data for a single client, I might use the following URI:
GET /client/xyz/ # xyx is the accountnumber used to identify the client.
I would use a GET method, since REST describes GET as being the method to use when retrieving data from the server.
The data could theoretically be returned in HTML, since REST is not a standard but more like a series of flexible guidelines; however, to really decouple my data from my user interface, I would choose to use something platform independent like JSON or XML to represent the data.
Next, when adding a client to the collection on the server, I would use the /client/ URI pattern, but I would use the HTTP Method POST, which is used when adding a resource to a collection on the server.
# Pass the data as JSON to the server and tell the server to add the client to the
# collection
POST /client/ {"accountnumber":"abc" , "Name" : "Jones" , "Location" : "Florida"}
If I were to modify an existing record on the server or replace it, I would most likely use the HTTP Method PUT, since REST guidelines say that PUT should be used if repeating the same operation repeatedly would not change the state of the server.
# Replace the client abc with a new resource
PUT /client/abc/ {"accountnumber":"abc" , "Name" : "Bob Jones" , "Location" : "Florida"}
The general idea behind REST is that it is used to identify a resource and then take action on that resource based on what HTTP Method is used.
If you insist on coupling your data with your view, one way accomplish this and retrieve the actual form, with the client data, could be to represent the form as a resource itself:
GET /client/abc/htmlform/
This URL would of course return your client data for client abc, but in an HTML form that would be rendered by the browser.
While my style of coding utilizes data transports such as JSON or XML to abstract and separate my data from my view, you could very well transport that data as HTML. However, the advantage of using JSON or XML is that your RESTful API becomes platform independent. If you ever expand your API to where other developers wish to consume it, they can do so, regardless of what specific platform or programming language they are using. In other words, the API could be used my PHP, Java, C#, Python, Ruby, or Perl developers.
In other words, any language or platform that can make HTTP requests and can send GET, POST, PUT, DELETE requests can be used to extend or build upon your API. This is the true advantage of REST.
For more information on setting up your controllers to use REST with Spring MVC, see this question. Additionally, check out the Spring MVC Documentation for more information.
Also, if you haven't checked out the Wikipedia article on REST, I strongly encourage you to do so. Finally, another good, classic read on REST is How I Explained REST To My Wife. Enjoy.