I'm writing a Swagger specification for an future public API that requires a very detailed and clean documentation. Is there a way to reference/link/point to another endpoint at some other location in the swagger.yml file?
For example, here is what I am trying to achieve:
paths:
/my/endpoint:
post:
tags:
- Some tag
summary: Do things
description: >
This endpoint does things.
See /my/otherEndpoint for stuff # Here I would like to have some kind of hyperlink
operationId: doThings
consumes:
- application/json
produces:
- application/json
parameters:
...
responses:
...
/my/otherEndpoint: # This is the endpoint to be referenced to
get:
...
I have found that $ref does not help because it simply replaces itself with the contents of the reference.
Can Swagger do such a thing?
Swagger UI provides permalinks for tags and operations if it's configured with the deepLinking: true option. These permalinks are generated based on the tag names and operationId (or if there are no operationId - based on the endpoint names and HTTP verbs).
index.html#/tagName
index.html#/tagName/operationId
You can use these permalinks in your Markdown markup:
description: >
This endpoint does things.
See [/my/otherEndpoint](#/tagName/myOtherEndpointId) for stuff
Notes:
Markdown links (such as above) currently open in a new browser tab (as with target="_blank") - see issue #3473.
HTML-formatted links foobar currently don't work.
Swagger Editor does not support such permalinks.
Related
Consider HTML. You write a tag <img src="http://example.com/image.png"/> and the browser retrieves the image at the location specified. I'm designing my API to use a similar mechanism where it's up to the server where any secondary resources and it supplies the location of those resources in the form of a URL.
I'm writing an OpenAPI document to describe all the JSON structures that are sent up to and returned by the server. It works great except I don't know how to express the relationship between the URL inside the response to the first resource to the second resource.
openapi: 3.0.3
info:
title: Minimal Spec for Question.
version: 0.0.0
paths:
/firstRefToSecond:
get:
description: Gets some data including a reference to a secondary resource.
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
RefToSecond:
type: string
description: The URL to the second resource.
example: "http://example.org/second"
/secondResourceExampleUrlNotActuallyThisUrl:
get:
description:
The second resource.
Found at the URL pointed to by RefToSecond.
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
Data:
type: integer
description: The data.
example: 12
Here, the second "path" is simply a placeholder for the second URL. I would prefer not to have that placeholder at all and instead substitute the path for wherever that URL points.
Is there a way in OpenAPI to express this relationship between the "refToSecond" URL property and the requirements of what that secondary interaction would look like, without linking it to an explicit URL set in advance?
Is there a way in OpenAPI to express this relationship between the "refToSecond" URL property and the requirements of what that secondary interaction would look like, without linking it to an explicit URL set in advance?
It is possible to formally express a relationship between the response of an operation and another request URL: See the Link feature. The section "Runtime Expression Syntax" is apparently helpful for your case. (Disclaimer: I have never seen this feature being used anywhere in practice so far.)
But this only allows to express the relation to the operation that is available at the server-defined URL. You cannot specify dynamic endpoints in OpenAPI, so you cannot provide a detailed description of the request and response (except in the way you showed in the question).
I have a requirement to route all the API calls which meets some pattern, to a specific service. For example "/register/student", "register/teacher", "register/employee" should all go to one micro service. Can I define the above path (not absolute path for each API) using some wild card or pattern so that any request which matches the patter: "/register/**", should go to one specific micro service.
You can do it in the path definition using path parameters and operation switches to control the flow of various patterns.
paths:
'register/{myParam}':
get:
responses:
'200':
description: 200 OK
parameters:
- name: myParam
type: string
in: path
required: true
Hi you can create a "Base Path" "/resgister" , then you can create the path "strong text/" asociated with some http method (get, post,...). Then in the you can usae javascript/gatewayscrip and some regex to filter $(request.path) and $(request.search) for your logic.
But if you whant to send all the request to some unique specific micro service, you only need to do the first part of the path and then use a "Proxy" politic.
I've been taking several hours fiddling this Resource Mapping for no luck. I have put a new node in /etc/map/http named GoogleAnalyticsMap. It had the following properties:
Name: jcr:primaryType
Type: Name
Value: sling:Mapping
Name: sling:internalRedirect
Type: String
Value: /content/dam/website/Common/my_google_analytics_key.html
Name: sling:match
Type: String
Value: [^/]+/[^/]+/my_google_analytics_key.html
Funnily, when i checked to /system/console/jcrresolver or Adobe CQ Web Console Sling Resource Resolver. It resolves into the following
Pattern: ^http/[^/]+/[^/]+/my_google_analytics_key.html
Replacement: /content/dam/website/Common/my_google_analytics_key.html
Redirect: internal
I have no idea how they could register ^[^/]+/[^/]+/welcome$ as shown in the example and did not have the 'http' there. Nevertheless, whenever i try to hit the pattern locally (i.e. http://localhost:4502/my_google_analytics_key.html) it only shows resource not found. Also checked through the Configuration test section that available in Adobe CQ Web Console Sling Resource Resolver it says that it can't resolve. Did i miss something?
, type=sling:nonexisting, path=/my_google_analytics_key.html, resource=[NonExistingResource, path=/my_google_analytics_key.html]
Thank you for the help.
p.s. i've checked the Sling documentation also, however, it baffles me that i can't add sling:alias, perhaps its also something to do with the sling version. Nevertheless, i should ask this as second question later, once the sling:match is working properly.
Edit: fiddling a bit, changing the sling:match to localhost.4502/google.html does let it to redirect localhost:4502/google.html to the desired DAM item. Well, i'm still asking for 'domain-free' matching though.. so i have no trouble when using the mapping for all environment i have..
Edit, Updates:
Apparently due to me put the new sling:Mapping under http folder it will always prefix the path with http. Perhaps the example is meant to be put not under http folder.
Next item is, it will always assume the matching item will be protocols, domain, and port separated by dots (yes, even \. is not a valid input and CQ or rather sling will sanitize it somehow). Something like *.(4502|4503|80|443)/my_google_analytics_key.html will accept any domains and those designated ports. I do wonder if it really the case, since they says regex but it does not feel so much regex.
Some says that sling:internalRedirect should be a String[] - yes i know the docs says String. I have not test this further and take it as it is..
I'm currently working on a REST API, trying to design it with most best practices as possible.
I work with Symfony2 PHP framework but some of my questions are valid for any REST API i guess.
Starting from the base design for a particular resource :
GET /resource - Get all resources
POST /resource - Create resource
GET /resource/{id} - Get resource with id={id}
PUT|PATCH /resource/{id} - Edit the resource with id={id}
DELETE /resource/{id} - Delete the resource with id={id}
Supposing my resource has complex rules while updating.
It has a "status" field, (a float for example), that can be updated only by following a particular scheme
It has a "schedule" field (a datetime), with different choices available that are not always the same
How am I supposed to expose those rules to the API consumer ? For the schedule field, how am I supposed to provide the different choices available at the current time ?
About the Symfony server-side part, I followed most of the recommandations of this walkthrough : http://williamdurand.fr/2012/08/02/rest-apis-with-symfony2-the-right-way/
My POST, PUT & PATCH actions are handled with Symfony Forms, so most of the rules are processed by Symfony constraints/validations features.
But form binding is quite limited, let's supposed I want to trigger a particular event if the user change the status field from 2 to 3? What is the best way to do that ?
Thanks in advance.
HTTP has another verb you aren't using: OPTIONS. You can use this to list the schedule options.
Here's a blog article about it: http://zacstewart.com/2012/04/14/http-options-method.html
As for updating the status, I would reuse POST and include an action in the field. Example:
POST
{
"type": "update",
"status": 3
}
Modified REST:
GET /resource - Get all resources
POST /resource - Create resource
GET /resource/{id} - Get resource with id={id}
PUT|PATCH /resource/{id} - Edit the resource with id={id}
DELETE /resource/{id} - Delete the resource with id={id}
OPTIONS /resource/{id} - Retrieve options of resource with id={id}
Keep in mind that you can pass params along in the body for everything but GET and you can pass any params in the URL for GET.
I have zero knowledge on Symfony2, so I'll just concentrate on your more generic REST how-to qustion about exposing rules.
Give the consumers of your REST API a documentation. It's the first thing they will hit before actually playing with your API. Use tools for that, from auto-generated help pages to 3'rd party providers like Apiary.io or alike.
Create meaningful responses when consumers send "wrong" requests: use correct http response status codes (Bad request, Conflict, etc.) when request parameters are missing or invalid.
If your REST api is relaxed, it can also include information about what went wrong and how to resolve the problem in the response body.
What worked well for me in the past was to have a generic ErrorMessage entity that was returned upon each non-successful request, containing a title, an error description, and a dedicated more technical "dev-description" which can be enabled/disabled for test/production on the server side.
In my case, my consumers all know that they can get either the expected response entity in case of success, or that generic ErrorMessage entity in the response in case of failure.
If you can desribe your rules, why not provide those as meta information for your service? Eg. in my case I know I have a set of parameters, each having a set of available options. Think of the parameters as the key in a query string, and the options as the values for that key. In a complex world, parameter options depend on other parameter options, eg. in my case the available options for parameter B are dependent of what option(s) are "selected" for parameter A. I can expose those dependencies by providing a "metadata" resource in my REST api, eg. a JSON stucture listing all parameters and all options for those parameters, and for each option adding a "requires" section desribing that that option is only "available" if parameter xy has selected option p and q.
This allows my consumers to - with a single request to that meta data resource - create a "state-machine" on the client side. I hope you get the picture.
Here is my understanding of REST-full way to handle updates and advertise update operations to API client.
This is based on this wonderful book and Fowler's article about REST with some additions of File Levels of Media Type and article about Restfull CQRS. Basically you use PUT for update and pass the operation via content type and advertise content type via mediaType in hypermedia controls.
All operations which are available for current state of your resource are listed among hypermedia controls which are passed with representation of resource like this:
<myresource>
<status>ACTIVE</status>
<some-field with-attribute="value"/>
<some-other-field/>
<!-- other fields representing state of resource -->
<link rel = "self"
uri = "/resource/1234"/>
<link rel = "/linkrels/resource/changeStatus"
uri = "/resource/1234"
mediaType = "application/vnd.myapp+xml;domain-model=ChangeStatusCommand"/>
<link rel = "/linkrels/resource/changeSchedule"
uri = "/resource/1234"
mediaType = "application/vnd.myapp+xml;domain-model=ChangeScheduleCommand"/>
<link rel = "/linkrels/help"
uri = "/help/resource"/>
</myresource>
Links together with mediaType gives enough information what command is allowed. In many cases this should be something very specific to current state of resource. For example if you can move it from status ACTIVE to TRASHED than command should be named not StatusChange but TrashCommand and so on.
I have downloaded swagger ui and experimenting it locally. It works fine in scenarios like "path", "body" , and "query" . But most of my use cases use rest comments.
i.e /resourcePath/;tags
URI to retrieve the tags of a specific resource.
When I try this the the UI gets jumbled when adding the semi colon and malformed the sorted UI and cannot go beyond this.
So is this a known limitation ? Is there a workaround to accomplish this target ?
Appreciate any input to this..
Swagger is expecting you to specify path params in curly-brackets like {tags} and query params as comma-delimited, such as id=1,2,3,4. Some frameworks use semi-colons as delimiters but swagger likes commas.
Can you describe more what you're looking to do, with a more concrete example? Per design, comments on the api belong in the description and notes fields for operations, please see swagger-core wiki for details.
The Swagger codegen project has a validator which can be used to verify that your spec is properly formatted.