Powerd911 – Numéro #1 au Canada

About API AccountManagement from TM Forum – swagger / JSON language

{
« swagger »: « 2.0 »,		 Every Swagger specification starts with the Swagger version, 2.0 being the latest version  
« info »: { The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in the Swagger-UI for convenience.  
« title »: « Account Management », Required. The title of the application.  
« description »: « This is Swagger UI environment generated for the TMF Account Management specification », A short description of the application. GFM syntax can be used for rich text representation.  
« version »: « 2.1 » }, Required Provides the version of the application API (not to be confused with the specification version).  
« schemes »: [« https »], « host »: « serverRoot », « basePath »: « /tmf-api/accountManagement/v2/ », URL structure  
« consumes »: [  « application/json »],  An API can accept and return data in different formats, the most common being JSON and XML.  
« produces »: [ « application/json »] An API can accept and return data in different formats, the most common being JSON and XML.  
« paths »: {« /partyAccount »: {  The paths section defines individual endpoints (paths) in your API, and the HTTP methods (operations) supported by these endpoints. For example, GET /partyAccount can be described as:  
« get »: { For each path, you define operations (HTTP methods) that can be used to access that path. Swagger 2.0 supports get, post, put, patch, delete, head, and options. A single path can support multiple operations, for example, GET /users to get a list of users and POST /users to add a new user. Swagger defines a unique operation as a combination of a path and an HTTP method. This means that two GET or two POST methods for the same path are not allowed – even if they have different parameters (parameters have no effect on uniqueness). Minimal example of an operation:  
« operationId »: « listPartyAccount », Each operation may specify a unique operationId. Some code generators use this value to name the corresponding methods in code.  
« summary »: « List or find ‘PartyAccount’ objects », A short summary and a longer description of what the operation does. description can be multi-line and supports GitHub Flavored Markdown for rich text representation.  
« tags »: [« partyAccount »],  tags are used to group operations in Swagger UI.  
« parameters »: [{ Operations can have parameters that can be passed via URL path (/users/{userId}), query string (/users?role=admin), headers (X-CustomHeader: Value) and request body. You can define the parameter types, format, whether they are required or optional, and other details:  
« type »: « string », « name »: « fields », « description »: « Comma separated properties to display in response », title, n Swagger, API operation parameters are defined under the parameters section in the operation definition. Each parameter has name, value type (for primitive value parameters) or schema (for request body), and optional description. Here is an example:  
« required »: false, By default, Swagger treats all request parameters as optional. You can add required: true to mark a parameter as required. Note that path parameters must have required: true, because they are always required.  
« in »: « query »} Query parameters are the most common type of parameters. They appear at the end of the request URL after a question mark (?), with different name=value pairs separated by ampersands (&). Query parameters can be required and optional.  
« responses »: { « 200 »: {  For each operation, you can define possible status codes, such as 200 OK or 404 Not Found, and schema of the response body. Schemas can be defined inline or referenced from an external definition via $ref. You can also provide example responses for different content types.  
« description »: « Ok », Under responses, each response definition starts with a status code, such as 200 or 404. An operation typically returns one successful status code and one or more error statuses. Each response status requires a description. For example, you can describe the conditions for error responses. GitHub Flavored Markdown can be used for rich text representation.  
« schema »: { « items »: {« $ref »: « #/definitions/PartyAccount »}, « type »: « array »}}, 

The schema keyword is used to describe the response body. A schema can define:

  • object or array – typically used with JSON and XML APIs,
  • a primitive such as a number or string – used for plain text responses,
  • file (see below).

Schema can be defined inline in the operation or defined at the root level and referenced via $ref. This is useful if multiple responses use the same schema.

Unlike JSON Schema, the items keyword is required in arrays. The value of items is a schema that describes the type and format of array items. Arrays can be nested.

  

« 400 »: { « description »: « Bad Request »,
« schema »: { « $ref »: « #/definitions/Error » }},

« 401 »: {« description »: « Unauthorized »,
« 403 »: {« description »: « Forbidden »,
« 404 »: {« description »: « Not Found »,
« 405 »: {« description »: « Method Not allowed »,
« 409 »: {« description »: « Conflict »,
« 500 »: {« description »: « Internal Server Error »,

    
     
     
     
By Benoit Le Nabec | 18/08/2018 | PowerAMC | No Comments |

Laisser un commentaire