Skip to content

1.2) Rest

Jump to bottom
Thomas Lapierre edited this page Jun 29, 2021 · 17 revisions

Summary

Warning:

The documentation of "Objet" and "Rest" is not up to date! It is currently being changed. Please refer to the examples or the Java class diagram.

Global structure

Objects definition

Rest definition

Rest

Field Name Type Required Description
<info> Info object true Provides metadata about the API. The metadata can be used by the clients if needed.
<basePath> String false The base path on which the API is served, which is relative to the host. If it is not included, the API is served directly under the host. The value MUST start with a leading slash (/).
<host> String false The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the host is not included, the host serving the documentation is to be used (including the port).
<tags> [Tag object] false A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. The tags that are not declared may be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
<paths> [Path object] true The available paths and operations for the API.
<schemes> [String] false Possible values are : "http", "https", "ws", "wss"

Structure

<rest>

     <info>...</info>

     <basePath>...</basePath>

     <host>...</host>

     <tags>...</tags>

     <paths>...</paths>

     <schemes>  
          <scheme>...</scheme>  
          <scheme>...</scheme>  
          ...  
     </schemes>

</rest>

Info object

Field Name Type Required Description
<description> String false A short description of the application.
<version> String true Provides the version of the application API (not to be confused with the specification version)
<title> String true The title of the application.
<contact-name> String false The contact name for the exposed API.
<contact-email> String false The contact email for the exposed API.
<contact-url> String false The contact url for the exposed API.
<licence-name> String true if licence-url is defined The licence name for the exposed API.
<licence-url> String false The licence url for the exposed API.
<terms-of-service> String false The Terms of Service for the API.

Structure

<info>

     <description>...</description>

     <version>...</version>

     <title>...</title>

     <contact-name>...</contact-name>

     <contact-email>...</contact-email>

     <contact-url>...</contact-url>

     <licence-name>...</contact-name>

     <licence-url>...</licence-url>

     <terms-of-service>...</terms-of-service>

</info>

Path object

Field Name Type Required Description
<name> String true A relative path to an individual endpoint. The field name MUST begin with a slash.
<methods> [Method object] true Description of the different methods

Structure

<path>

     <name>...</name>

     <methods>...</methods>

</path>

Method object

Field Name Type Required Description
<type> String true Type of the method. Possible values : get, put, post, delete, options, head, patch.
<tags> [String] false List of tags in order to group operations. The tags must refer to those declared in the <tags> of the Rest Object
<operation-id> String false Unique string used to identify the operation. The id MUST be unique among all operations described in the API.
<produces> [String] false A list of MIME types the operation can produce.
<parameters> [Parameter object ] false A list of parameters that are applicable for this operation.
<responses> [Response object] true The list of possible responses as they are returned from executing this operation.
<summary> String false A short summary of what the operation does. For maximum readability in the swagger-ui, this field SHOULD be less than 120 characters.
<deprecated> Boolean false Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is false.
<description> String false A verbose explanation of the operation behavior.
<consumes> [String] false A list of MIME types the operation can consume.

Structure

<method>

     <type>...</type>

     <tags>
          <tag>...</tag>
          <tag>...</tag>
     </tags>

     <operation-id>...</operation-id>

     <produces>...</produces>

     <parameters>...</parameters>

     <responses>...</responses>

     <summary>...</summary>

     <deprecated>...</deprecated>

     <description>...</description>

     <consumes>...</consumes>

</method>

Response Object

Field Name Type Required Description
<name> String true Name response. Possible values : "default" or HTTP Status Code
<description> String true A short description of the response.
<schema> Schema object false A definition of the response structure. It can be a primitive, an array or an object. If this field does not exist, it means no content is returned as part of the response.

Structure

<response>

     <name>...</name>

     <description>...</description>

     <schema>...</schema>

</response>

Schema Object

Field Name Type Required Description
<ref> String true The ref tag should contains the name of the object refered. This object should be declared in the objects definition tag.

Structure

<schema>

     <ref>...</ref>

</schema>

Parameter object

Field Name Type Required Description
<in> String true The location of the parameter. Possible values are "query", "header", "path", "formData" or "body". If <in> = "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object. See Path Templating for further information. For all other cases, the name corresponds to the parameter name used based on the in property.
<name> String true The name of the parameter. Parameter names are case sensitive.
<required> Boolean true if <in> = "path" Determines whether this parameter is mandatory. If the parameter is in "path", this property is required and its value MUST be true. Otherwise, the property MAY be included and its default value is false.
<schema> Schema object true if <in> is equal to "body" The schema defining the type used for the body parameter.
<type> Data type or "file" true if <in> is any value other than "body" The type of the parameter. Since the parameter is not located at the request body, it is limited to simple types (that is, not an object). If type is "file", the consumes MUST be either "multipart/form-data", " application/x-www-form-urlencoded" or both and the parameter MUST be in "formData".
<description> String false A brief description of the parameter. This could contain examples of use.

Structure

<parameter>

     <in>...</in>

     <name>...</name>

     <required>...</required>
  
     <schema>...</schema>

     <type>...</type>
    
     <description>...</description>

</parameter>

Tag object

Field Name Type Required Description
<name> String true The name of the tag.
<description> String false A short description for the tag.
<external-docs> ExternalDocs object false Additional external documentation for this tag.

Structure

<tag>

     <name>...</name>

     <description>...</description>

     <external-docs>...</external-docs>

</tag>

ExternalDocs Object

Field Name Type Required Description
<description> String false A short description of the target documentation.
<url> String true The URL for the target documentation. Value MUST be in the format of a URL.

Structure

<external-docs>

     <description>...</description>

     <url>...</url>

</external-docs>

Go to top

Edited by Thomas Lapierre, 2021

Clone this wiki locally