黄色视频

    1. <form id=QUkGStDXb><nobr id=QUkGStDXb></nobr></form>
      <address id=QUkGStDXb><nobr id=QUkGStDXb><nobr id=QUkGStDXb></nobr></nobr></address>

      Show Navigation

      swagger

      Grails Swagger Plugin

      Owner: ajay-kumar | 1.0.1 | Apr 6, 2019 | Package | Issues | Source | License: Apache-2.0

      20
      
      dependencies {
          compile 'swagger:swagger:1.0.1'
      }
      
                  

      Table of Contents

      1. Introduction

      2. Installation

      3. Configuration

      4. How To Use

      5. Sample Code

      Introduction

      This plugin provides easy integration of Swagger with GRAILS. It is highly aligned with Swagger and its 2.0 specification, thereby creating a language-agnostic interface to REST APIs. This allows both humans and computers to discover and understand the capabilities of service without access to source code, documentation simply through network traffic inspection

      Installation

      1. Add repository and dependency in your build.gradle file using below lines:-

      repositories {
          maven { url "https://dl.bintray.com/ajay-kumar/plugins" }
      }
      
      dependencies {
          compile 'org.grails.plugins:swagger:1.0.1'
      }
      Note
      If you are using version 1.0.0 or older, your logging might not work as per your expected logback config file.
      This is an issue with swagger servlet jar. Issue has already been raised for this:- https://github.com/swagger-api/swagger-core/issues/1813
      However, you can easily overcome this issue by explicitly setting the name of your logback configuration file in your build.gradle using:-
      bootRun {
          jvmArgs = [
                  "-Dlogging.config=${project.projectDir}/grails-app/conf/logback.groovy"
          ]
      }
      Note
      Alternatively, you can also pass the name of logback configuration file using JVM argumants or system properties as follow:-
      java -Dlogback.configurationFile=/path/to/config.xml

      Please refer this link to know more about how to set logback config file location.

      Configuration

      1. Expose an API from your application by adding line- "/apidoc/$action?/$id?"(controller: "apiDoc", action: "getDocuments") in your UrlMappings.groovy file under the ???????static mappings??????? block.

        Note
        This API will be used to generate swagger document. So if you want to access your swagger document with different URI, do the necessary changes here eg if you want to expose your swagger document using URI- api/vi/myDoc then you should add "/api/vi/myDoc/$action?/$id?"(controller: "apiDoc", action: "getDocuments") in your UrlMappings.groovy file under the ???????static mappings??????? block.
      2. If your application is located behind a proxy that enables the required CORS headers then you need to enable CORS support too.

        Note
        Please read this article to know if CORS support needs to be enabled or not for your application.
      3. Create a configuration file (eg application.groovy) in conf folder present inside your application????????s grails-app folder (if not created yet) and add the following configuration details:-

      application.groovy

      import io.swagger.models.Scheme
      
      swagger {
         info {
             description = "Move your app forward with the Swagger API Documentation"
             version = "ttn-swagger-1.0.0"
             title = "Swagger API"
             termsOfServices = "http://swagger.io/"
             contact {
                 name = "Contact Us"
                 url = "http://swagger.io"
                 email = "[email protected]"
             }
             license {
                 name = "licence under http://www.tothenew.com/"
                 url = "http://www.tothenew.com/"
             }
         }
         schemes = [Scheme.HTTP]
         consumes = ["application/json"]
      }

      How To Use

      1. Next there is a good example to show you how the set of annotations can be used to generate swagger documentation. Please refer this sample example to know more.

      2. A set of annotations is used to generate swagger documentation. Please refer this link to know more about the available annotations.

        Note
        Only annotations provided by swagger-core are supported and JAX-RS annotations are not supported.
      3. Annotate your controller class with annotation @io.swagger.annotations.Api to make it available for documentation. For more details see sample code.

      4. Annotate your methods/action of controller with @io.swagger.annotations.ApiOperation, @io.swagger.annotations.ApiResponses, @io.swagger.annotations.ApiImplicitParams to include various method level information in your documentation. See next section to know more details about how to use these annotations.

        Note
        The value corresponding to ???????value??????? attribute of API annotation present at class level and the value corresponding to ???????nickname??????? attribute of ???????ApiOperation??????? annotation present at method level when combined together, it should form the relative end point provided in UrlMappings.groovy. Refer to explanation below the provided sample.
      5. If the ???????value??????? attribute of ???????API??????? annotation present at class label is not provided then it defaults to the controller name.

      6. The ???????nickname??????? attribute of ???????ApiOperation??????? annotation is also new and serves as unique name for the operation. If this is not provided this default to the method name

        Note
        If you are not explicitly providing the mapping of your actions defined in controller to the end points using UrlMappings.groovy file, you need not to bother about ???????value??????? attribute of ???????API??????? annotation present at class label and ???????nickname??????? attribute of ???????ApiOperation??????? annotation present at method label. Its default value will work fine.

      Sample Code

      Assume your UrlMappings.groovy class is as follow:-

      package testswaggerplugin
      
      class UrlMappings {
         static mappings = {
             "/$controller/$action?/$id?(.$format)?" {
                 constraints {
                     // apply constraints here
                 }
             }
             "/"(view: "/index")
             "500"(view: '/error')
             "404"(view: '/notFound')
             "/api/v1/city/$cityId"(controller: "city", action: "getCity", method: "GET")
             "/api/v1/city/list"(controller: "city", action: "getCityList", method: "GET")
             "/api/v1/city/createUpdate"(controller: "city", action: "createOrUpdateCity", method: "POST")
             "/api/v1/city/$cityId"(controller: "city", action: "deleteCity", method: "DELETE")
         }
      }

      Then your swagger annotated CityController.groovy is as follow:-

      package testswaggerplugin
      
      import CityDTO
      import ResponseDTO
      import grails.converters.JSON
      import io.swagger.annotations.*
      
      @Api(value = "/api/v1", tags = ["City"], description = "City Api's")
      class CityController {
      
         static namespace = 'v1'
      
         @ApiOperation(
                 value = "List Cities",
                 nickname = "city/{cityId}",
                 produces = "application/json",
                 consumes = "application/json",
                 httpMethod = "GET",
                 response = ResponseDTO.class
                 )
         @ApiResponses([
                 @ApiResponse(code = 405,
                 message = "Method Not Allowed. Only GET is allowed"),
      
                 @ApiResponse(code = 404,
                 message = "Method Not Found")
                 ])
         @ApiImplicitParams([
                 @ApiImplicitParam(name = "cityId",
                 paramType = "path",
                 required = true,
                 value = "City Id",
                 dataType = "string"),
      
                 @ApiImplicitParam(name = "applicationType",
                 paramType = "header",
                 required = true,
                 defaultValue = "web",
                 value = "Application Types",
                 dataType = "string"),
      
                 @ApiImplicitParam(name = "Accept-Language",
                 paramType = "header",
                 required = true,
                 defaultValue = "en",
                 value = "Accept-Language",
                 dataType = "string")
         ])
         def getCity(String cityId) {
            // Demonstrate how to use swagger annotation to generate documentation
            // for method which accepts cityId as parameter provided in url path.
      
             render(new ResponseDTO(status: true,
             message: "New Delhi",
             data: ["key1": "value1", "key2": "value2"]) as JSON)
         }
      
         @ApiOperation(
                 value = "List Cities",
                 nickname = "city/list",
                 produces = "application/json",
                 consumes = "application/json",
                 httpMethod = "GET",
                 response = ResponseDTO.class
                 )
         @ApiResponses([
                 @ApiResponse(code = 405,
                 message = "Method Not Allowed. Only GET is allowed"),
      
                 @ApiResponse(code = 404,
                 message = "Method Not Found")
                 ])
      
         @ApiImplicitParams([
                 @ApiImplicitParam(name = "offset",
                 paramType = "query", required = true,
                 value = "Offset", dataType = "integer"),
      
                 @ApiImplicitParam(name = "limit",
                 paramType = "query",
                 required = true,
                 value = "Max size",
                 dataType = "integer"),
      
                 @ApiImplicitParam(name = "applicationType",
                 paramType = "header",
                 required = true,
                 defaultValue = "web",
                 value = "Application Types",
                 dataType = "string"),
      
                 @ApiImplicitParam(name = "Accept-Language",
                 paramType = "header",
                 required = true,
                 defaultValue = "en",
                 value = "Accept-Language",
                 dataType = "string")
         ])
         def getCityList(Integer offset, Integer limit) {
            // Demonstrate how to use swagger annotation to generate documentation
            // for method which accepts offset and limit as query parameter.
             render(new ResponseDTO(status: true,
             message: "City List fetched successfully",
             data: ["key1": "value1", "key2": "value2"]) as JSON)
         }
      
         @ApiOperation(
                 value = "Create City",
                 notes = "Creates a new City. Accepts a City json.",
                 produces = "application/json",
                 consumes = "application/json",
                 httpMethod = "POST",
                 nickname = "/city/createUpdate",
                 response = ResponseDTO.class
                 )
         @ApiResponses([
                 @ApiResponse(code = 405,
                 message = "Method Not Allowed. Only POST is allowed"),
      
                 @ApiResponse(code = 404,
                 message = "Method Not Found")
         ])
         @ApiImplicitParams([
                 @ApiImplicitParam(name = "body",
                 paramType = "body",
                 required = true,
                 value = "Requires City Details",
                 dataType = "CityDTO"),
      
                 @ApiImplicitParam(name = "applicationType",
                 paramType = "header",
                 required = true,
                 defaultValue = "web",
                 value = "Application Types",
                 dataType = "string"),
      
                 @ApiImplicitParam(name = "Accept-Language",
                 paramType = "header",
                 required = true,
                 defaultValue = "en",
                 value = "Accept-Language",
                 dataType = "string")
         ])
         def createOrUpdateCity(CityDTO cityDTO) {
             render(new ResponseDTO(status: true,
             message: "City updated successfully",
             data: cityDTO) as JSON)
         }
      
         @ApiOperation(
                 value = "Delete City",
                 notes = "Deletes a City.Accepts a City ID .",
                 produces = "application/json",
                 consumes = "application/json",
                 httpMethod = "DELETE",
                 nickname = "/city/{cityId}",
                 response = ResponseDTO.class
                 )
         @ApiResponses([
                 @ApiResponse(code = 405,
                 message = "Method Not Allowed. Only Delete is allowed"),
                 @ApiResponse(code = 404,
                 message = "Method Not Found")])
      
         @ApiImplicitParams([
                 @ApiImplicitParam(name = 'cityId',
                 paramType = 'path',
                 required = true, value = "Requires City id for delete",
                 dataType = "string"),
      
                 @ApiImplicitParam(name = "applicationType",
                 paramType = "header",
                 required = true,
                 defaultValue = "web",
                 value = "Application Types",
                 dataType = "string"),
      
                 @ApiImplicitParam(name = "Accept-Language",
                 paramType = "header",
                 required = true,
                 defaultValue = "en",
                 value = "Accept-Language",
                 dataType = "string")
         ])
         def deleteCity(String cityId) {
             render(new ResponseDTO(status: true,
             message: "City deleted successfully") as JSON)
         }
      
          @ApiOperation(value = "Upload File Example",
                  notes = "Upload File Example",
                  nickname = "/city/upload",
                  response = ResponseDTO.class,
                  httpMethod = "POST")
          @ApiResponses(value = [
                  @ApiResponse(code = 405, message = "Method Not Allowed. Only POST is allowed"),
                  @ApiResponse(code = 404, message = "Method Not Found")
          ])
          @ApiImplicitParams([
                  @ApiImplicitParam(name = 'cityFile', paramType = 'form',
                          required = true,
                          value = "Requires File Containing City Information",
                          dataType = "java.io.File")])
          ResponseDTO uploadCityData(HttpServletRequest request) {
            // Demonstrate how to use swagger annotation to generate documentation
            // for method which accepts MultipartFile in request.
              MultipartFile file = request.getFile('cityFile')
              //Do with file
              (new ResponseDTO(status: true, message: "File with name ${file?.originalFilename} uploaded successfully") as JSON)
          }
      }

      In the sample code provided above you can find that CityController is annotated with @Api(value = "/api/v1", tags = ["City"], description = "City Api’s"). So the value corresponding to ???????value??????? attribute of ???????API??????? annotation present at this class label is "/api/v1".

      Similarly you can observe that getCity() method of CityController has annotation @ApiOperation(value = "List Cities", nickname = "city/{cityId}", produces = "application/json", consumes = "application/json", httpMethod = "GET", response = ResponseDTO.class). Hence the value corresponding to ???????nickname??????? attribute of ???????ApiOperation??????? annotation present at this method label is "city/{cityId}" and when these two values of API annotation and ApiOperation annotations are combined together it gives- "/api/v1/city/{cityId}".

      This combined value is Swagger’s way of specifying the end url- "/api/v1/city/$cityId" defined in UrlMappings.groovy file for (controller: "city", action: "getCity", method: "GET")

      HoMEmenuCopyrights 2015.All rights reserved.More welcome - Collect from power by english Blok number sss85786789633111 Copyright