Package org.apache.juneau.rest.annotation

Annotation Interface OpSwagger

@Retention(RUNTIME) public @interface OpSwagger
Extended annotation for RestOp.swagger().
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String[]
    consumes
    Defines the swagger field /paths/{path}/{method}/consumes.
    String
    deprecated
    Defines the swagger field /paths/{path}/{method}/deprecated.
    String[]
    description
    Defines the swagger field /paths/{path}/{method}/description.
    ExternalDocs
    externalDocs
    Defines the swagger field /paths/{path}/{method}/externalDocs.
    String
    operationId
    Defines the swagger field /paths/{path}/{method}/operationId.
    String[]
    parameters
    Defines the swagger field /paths/{path}/{method}/parameters.
    String[]
    produces
    Defines the swagger field /paths/{path}/{method}/consumes.
    String[]
    responses
    Defines the swagger field /paths/{path}/{method}/responses.
    String[]
    schemes
    Defines the swagger field /paths/{path}/{method}/schemes.
    String[]
    summary
    Defines the swagger field /paths/{path}/{method}/summary.
    String[]
    tags
    Optional tagging information for the exposed API.
    String[]
    value
    Free-form value for the swagger of a resource method.

  • Element Details

    • consumes

      String[] consumes
      Defines the swagger field /paths/{path}/{method}/consumes.

      Use this value to override the supported Content-Type media types defined by the parsers defined via RestOp.parsers().

      Notes:
      • The format is either a comma-delimited list of simple strings or a juneau-bean-swagger-v2 array.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      • Values defined on this annotation override values defined for the method in the class swagger.
      Returns:
      The annotation value.
      Default:
      {}

    • deprecated

      String deprecated
      Defines the swagger field /paths/{path}/{method}/deprecated.
      Example:

      @RestGet( swagger=@OpSwagger( deprecated=true ) )

      Notes:
      • The format is boolean.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      • Values defined on this annotation override values defined for the method in the class swagger.
      • If not specified, set to "true" if the method is annotated with @Deprecated
      Returns:
      The annotation value.
      Default:
      ""

    • description

      String[] description
      Defines the swagger field /paths/{path}/{method}/description.
      Notes:
      • The format is plain text.
        Multiple lines are concatenated with newlines.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      • Values defined on this annotation override values defined for the method in the class swagger.
      • If not specified, the value is pulled from RestOp.description().
      Returns:
      The annotation value.
      Default:
      {}

    • externalDocs

      ExternalDocs externalDocs
      Defines the swagger field /paths/{path}/{method}/externalDocs.
      Example:

      @RestGet( swagger=@OpSwagger( externalDocs=@ExternalDocs(url="http://juneau.apache.org") ) )

      Notes:
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      • Values defined on this annotation override values defined for the method in the class swagger.
      Returns:
      The annotation value.
      Default:
      @org.apache.juneau.annotation.ExternalDocs

    • operationId

      String operationId
      Defines the swagger field /paths/{path}/{method}/operationId.
      Notes:
      • The format is plain text.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      • Values defined on this annotation override values defined for the method in the class swagger.
      • If not specified, the value used is the Java method name.
      Returns:
      The annotation value.
      Default:
      ""

    • parameters

      String[] parameters
      Defines the swagger field /paths/{path}/{method}/parameters.

      This annotation is provided for documentation purposes and is used to populate the method "parameters" column on the Swagger page.

      Example:

      @RestPost( path="/{a}", description="This is my method.", swagger=@OpSwagger( parameters={ "{in:'path', name:'a', description:'The \\'a\\' attribute'},", "{in:'query', name:'b', description:'The \\'b\\' parameter', required:true},", "{in:'body', description:'The HTTP content'},", "{in:'header', name:'D', description:'The \\'D\\' header'}" } ) )

      Notes:
      • The format is a juneau-bean-swagger-v2 array consisting of the concatenated individual strings.
        The leading and trailing '[' and ']' characters are optional.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      Returns:
      The annotation value.
      Default:
      {}

    • produces

      String[] produces
      Defines the swagger field /paths/{path}/{method}/consumes.

      Use this value to override the supported Accept media types defined by the serializers defined via RestOp.serializers().

      Notes:
      • The format is either a comma-delimited list of simple strings or a juneau-bean-swagger-v2 array.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      • Values defined on this annotation override values defined for the method in the class swagger.
      Returns:
      The annotation value.
      Default:
      {}

    • responses

      String[] responses
      Defines the swagger field /paths/{path}/{method}/responses.

      This annotation is provided for documentation purposes and is used to populate the method "responses" column on the Swagger page.

      Example:

      @RestGet( path="/", swagger=@OpSwagger( responses={ "200:{ description:'Okay' },", "302:{ description:'Thing wasn't found here', headers={Location:{description:'The place to find the thing.'}}}" } ) )

      Notes:
      • The format is a juneau-bean-swagger-v2 objc consisting of the concatenated individual strings.
        The leading and trailing '{' and '}' characters are optional.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      Returns:
      The annotation value.
      Default:
      {}

    • schemes

      String[] schemes
      Defines the swagger field /paths/{path}/{method}/schemes.
      Notes:
      • The format is either a comma-delimited list of simple strings or a juneau-bean-swagger-v2 array.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      • Values defined on this annotation override values defined for the method in the class swagger.
      Returns:
      The annotation value.
      Default:
      {}

    • summary

      String[] summary
      Defines the swagger field /paths/{path}/{method}/summary.
      Notes:
      • The format is plain text.
        Multiple lines are concatenated with newlines.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      • Values defined on this annotation override values defined for the method in the class swagger.
      • If not specified, the value is pulled from RestOp.summary().
      Returns:
      The annotation value.
      Default:
      {}

    • tags

      String[] tags
      Optional tagging information for the exposed API.

      Used to populate the Swagger tags field.

      A comma-delimited list of tags for API documentation control.
      Tags can be used for logical grouping of operations by resources or any other qualifier.

      Example:

      @RestGet( swagger=@OpSwagger( tags="foo,bar" ) )

      Notes:
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      • Corresponds to the swagger field /paths/{path}/{method}/tags.
      Returns:
      The annotation value.
      Default:
      {}

    • value

      String[] value
      Free-form value for the swagger of a resource method.

      This is a juneau-bean-swagger-v2 object that makes up the swagger information for this resource method.

      The following are completely equivalent ways of defining the swagger description of a resource method:

      // Normal @RestPost( path="/pet", swagger=@OpSwagger( summary="Add pet", description="Adds a new pet to the store", tags="pet", externalDocs=@ExternalDocs( description="Home page", url="http://juneau.apache.org" ) ) )

      // Free-form @RestPost( path="/pet", swagger=@OpSwagger({ "summary: 'Add pet',", "description: 'Adds a new pet to the store',", "tags: ['pet'],", "externalDocs:{", "description: 'Home page',", "url: 'http://juneau.apache.org'", "}" }) )

      // Free-form with variables @RestPost( path="/pet", swagger=@OpSwagger("$L{addPetSwagger}") )

      // Contents of MyResource.properties addPetSwagger = { summary: "Add pet", description: "Adds a new pet to the store", tags: ["pet"], externalDocs:{ description: "Home page", url: "http://juneau.apache.org" } }

      The reasons why you may want to use this field include:

      • You want to pull in the entire Swagger JSON definition for this content from an external source such as a properties file.
      • You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification.
      Notes:
      • The format is a juneau-bean-swagger-v2 object.
      • The leading/trailing { } characters are optional.
        The following two example are considered equivalent:

        @OpSwagger("{summary: 'Add pet'}")

        @OpSwagger("summary: 'Add pet'")

      • Multiple lines are concatenated with newlines so that you can format the value to be readable.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      • Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation.
      Returns:
      The annotation value.
      Default:
      {}