swagger环境搭建及使用

swagger环境搭建及使用：
1，导入swagger所需要的jar包及插件 pom文件

      
        org.codehaus.gmaven
        groovy-maven-plugin
        2.0
        
          
            ${project.basedir}/src/main/swagger-spec/all/index.yaml
            ${project.basedir}/src/main/swagger-spec/api
          
          
            import io.swagger.parser.Swagger20Parser
            import io.swagger.parser.SwaggerResolver
            import io.swagger.util.Json
            import io.swagger.util.Yaml
            import org.apache.commons.io.FileUtils

            def parser = new Swagger20Parser()
            def path = properties['inFile']
            def swagger = parser.read(path, null)
            def resolver = new SwaggerResolver(swagger, null, path)
            resolver.resolve()
            def out = properties['outFile']
            Json.pretty().writeValue(new File(out + '.json'), swagger)
            Yaml.pretty().writeValue(new File(out + '.yaml'), swagger)
          
        
        
          
            io.swagger
            swagger-parser
            1.0.25
          
        
      
      
      
        io.swagger
        swagger-codegen-maven-plugin
        2.2.2
        
          
          ${project.basedir}/src/main/swagger-spec/api.json
          
swagger-codegen
          
          
          spring
          
          
          com.xforceplus.hera.api.spec.common.model
          com.xforceplus.hera.api.spec.common
          src/main/swagger-templates/spring
          
            src/main/java
            com.xforceplus.hera.api.spec.common.api
            com.xforceplus.hera.api.spec.common
            true
            true
            true
            java8
            
              jackson=true
            
            true
            Response=com.xforceplus.xplat.domain.Response
          
          true
        
      
      
      
        org.codehaus.mojo
        build-helper-maven-plugin
        1.12
        
          
            add-source
            generate-sources
            
              add-source
            
            
              
                swagger-codegen/src/main/java
              
            
          
        
      
2，按照pom中指定的文件创建目录结构，在src/main/swagger-spec/all目录下index.yaml文件编写：
    swagger: 2.0
    info:
      title: Xforce+ open API
      description: Xforce+ athena open API 1.0
      version: 1.0
    host: localhost:8081
    schemes:
      - http
      - https
    basePath: "/sapi-v1"
    tags:
      - name: "Account"
        description: "账户服务"
    produces:
      - application/json
    paths:
      /account/innerLogin:
        $ref: '../apis/login.yaml#/paths/innerLogin'
      /account/loginOut:
        $ref: '../apis/login.yaml#/paths/loginOut'
    在src/main/swagger-spec/apis目录下编写login.yaml：
    swagger: 2.0
    paths:
      innerLogin:
        post:
          summary: 内部员工登陆
          operationId: innerLogin
          parameters:
            - in: body
              name: data
              required: true
              schema:
                $ref: '../models/login.domain.yaml#/definitions/InnerLoginRequest'
          responses:
            '200':
              description: 登陆成功
              schema:
                $ref: '../models/login.domain.yaml#/definitions/Response'
          tags:
            - Login

      loginOut:
          post:
            summary: 内部员工登出
            operationId: loginOut
            parameters:
              - in: body
                name: data
                required: true
                schema:
                  $ref: '../models/login.domain.yaml#/definitions/InnerLogoutRequest'
            responses:
              '200':
                description: 退出成功
                schema:
                  $ref: '../models/login.domain.yaml#/definitions/Response'
            tags:
              - Logout
    在src/main/swagger-spec/models目录下编写login.domain.yaml文件：
    swagger: 2.0
    definitions:
      InnerLoginRequest:
        description: 用户登录
        properties:
          accountName:
            description: 登录名
            type: string
          password:
            type: string
            description: 登录密码
      Response:
          description: general Response object
          type: object
          properties:
            code:
              description: return code
              type: integer
              format: int32
            message:
              description: return message
              type: string
            result:
              description: result
              type: object
      InnerLogoutRequest:
          description: 用户退出
          properties:
            token:
              description: 校验信息
              type: string
            userId:
              type: string
              description: 用户名
3，先运行 groovy:execute命令生成api.json和api.yaml文件，然后执行swagger-codegen:generate命令生成
相应接口文档及请求参数对象