swagger环境搭建及使用

swagger环境搭建及使用：
1，导入swagger所需要的jar包及插件 pom文件
<!-- 合并swagge文档 -->
      <plugin>
        <groupId>org.codehaus.gmaven</groupId>
        <artifactId>groovy-maven-plugin</artifactId>
        <version>2.0</version>
        <configuration>
          <properties>
            <inFile>${project.basedir}/src/main/swagger-spec/all/index.yaml</inFile>
            <outFile>${project.basedir}/src/main/swagger-spec/api</outFile>
          </properties>
          <source>
            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)
          </source>
        </configuration>
        <dependencies>
          <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-parser</artifactId>
            <version>1.0.25</version>
          </dependency>
        </dependencies>
      </plugin>
      <!-- 基于swagger文档生成服务端代码 -->
      <plugin>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-codegen-maven-plugin</artifactId>
        <version>2.2.2</version>
        <configuration>
          <!-- specify the swagger yaml -->
          <inputSpec>${project.basedir}/src/main/swagger-spec/api.json</inputSpec>
          <output>swagger-codegen</output>
          <!--<output>swagger-codegen-javascript</output>-->
          <!-- target to generate -->
          <language>spring</language>
          <!--<language>javascript</language>-->
          <!-- pass any necessary config options -->
          <modelPackage>com.xforceplus.hera.api.spec.common.model</modelPackage>
          <invokerPackage>com.xforceplus.hera.api.spec.common</invokerPackage>
          <templateDirectory>src/main/swagger-templates/spring</templateDirectory>
          <configOptions>
            <sourceFolder>src/main/java</sourceFolder>
            <apiPackage>com.xforceplus.hera.api.spec.common.api</apiPackage>
            <basePackage>com.xforceplus.hera.api.spec.common</basePackage>
            <interfaceOnly>true</interfaceOnly>
            <java8>true</java8>
            <jdk8>true</jdk8>
            <dateLibrary>java8</dateLibrary>
            <additional-properties>
              jackson=true
            </additional-properties>
            <hideGenerationTimestamp>true</hideGenerationTimestamp>
            <import-mappings>Response=com.xforceplus.xplat.domain.Response</import-mappings>
          </configOptions>
          <verbose>true</verbose>
        </configuration>
      </plugin>
      <!-- 添加生成的source到maven -->
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <version>1.12</version>
        <executions>
          <execution>
            <id>add-source</id>
            <phase>generate-sources</phase>
            <goals>
              <goal>add-source</goal>
            </goals>
            <configuration>
              <sources>
                <source>swagger-codegen/src/main/java</source>
              </sources>
            </configuration>
          </execution>
        </executions>
      </plugin>
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命令生成
相应接口文档及请求参数对象