使用docker技术，将gitlab和swagger做一个有机的结合，达到的效果为：每次提交代码，都会自动生成swagger API文档。

以下是实现流程步骤：

代码和目录结构

docker-compose.yml文件书写

swagger_ui:
  image: swaggerapi/swagger-ui:latest
  container_name: swagger_ui
  ports:
    - "8080:8080"
  volumes:
    - ./swagger:/usr/share/nginx/html/swagger
swagger_validator:
  image: swaggerapi/swagger-validator:latest
  container_name: swagger_validator
  ports:
    - "8088:8080"
gitlab_ce:
  image: gitlab/gitlab-ce:latest
  container_name: gitlab_ce
  hostname: gitlab_ce
  ports:
    - "8090:80"
    - "8091:443"
    - "22:22"
  volumes:
    - ./gitlab/config:/etc/gitlab
    - ./gitlab/data:/var/opt/gitlab
    - ./gitlab/logs:/var/log/gitlab
gitlab_runner:
  image: gitlab/gitlab-runner:latest
  container_name: gitlab-runner
  links:
    - gitlab_ce
  ports:
    - "8099:80"
  volumes:
    - ./gitlab/gitlab-runner/config:/etc/gitlab-runner
    - /var/run/docker.sock:/var/run/docker.sock
    - ./swagger:/tmp

目录结构：

swagger-php

这是一个通过写API注释，生成swagger-json的小工具。
详情：http://zircote.com/swagger-php/
github地址：https://github.com/zircote/swagger-php

下载方法：

composer require zircote/swagger-php

使用方法：

使用composer下载后，运行指令:

./vendor/bin/swagger -o 目标路径  代码注释路径

gitlab-ce和gitlab-runner

这俩东西是密切相关的俩东西。
gitlab-ce和gitlab-runner的关系如下图所示：

默认情况下，gitlab和gitlab-ci是在一起的。现在只需连接gitlab(或者gitlab-ce)和gitlab-ci就好。

gitlab-ce 和 gitlab-runner 结合

首先按照上图所示的内容，写好docker-compose.yml 文件，建好目录，然后运行：docker-compose up -d
几个容器跑起来后，开始连接gitlab-ce和gitlab-runner两个容器。

gitlab-ce和gitlab-runner连接方式很简单：

• 网页打开gitlab-ce的地址(此处为：localhost:8090)

  
  特别注意地址和token，下一步骤用到

• 进入到gitlab-runner容器，输入如下指令:

$ gitlab-runner register

Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com )
## 输入你的gitlab地址（以上的地址）  
Please enter the gitlab-ci token for this runner
## gitlab的token(在gitlab的Admin Area中) 或者仓库的token(仓库->设置->Runner)，就是上图标注的token
Please enter the gitlab-ci description for this runner
## Runner描述信息
Please enter the gitlab-ci tags for this runner (comma separated):
## Runner的标签 可以指定仓库 只使用固定标签的Runner构建
Please enter the executor: parallels, shell, ssh, virtualbox, docker+machine, docker-ssh+machine, docker, docker-ssh, kubernetes:
## 这里我们选择shell
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

gitlab-runner实际上就是代码需要运行的环境，在此，我们只需要安装php7就好。

CI所需要的执行脚本书写

在所要提交的代码中加上.gitlab-ci.yml文件，此文件的作用就是制定CI在运行中的步骤，例如，先执行生成API文档，然后跑unit test，然后跑….等等流程性的东西，在此，我们暂时只需要生成API文档就好。

stages:
  - build
swagger:
  stage: build
  script:
    - bash ./swagger.sh
    - mv swagger.json /tmp/

以上可以说配置基本结束了。需要在gitlab上创建项目并运行起来。

swagger套装组件

swagger组件有不少，ui、validator、editor、code-gen等等，在此只用到swagger-ui和swagger-validator这俩。(想用什么随时加)

修改swagger-ui默认首页

打开swagger-ui的容器，把swagger-ui的默认首页修改一下。(默认是http://petstore.swagger.io/v2/swagger.json，不改也可以)

打开容器中的/usr/share/nginx/html/index.html文件，将如下信息修改:

改为生成的swagger文件地址。(在此为:localhost:8080/swagger/swagger.json)

使用swagger-validator验证生成的josn是否正确

这一步，最好是能在CI中做，如果验证不正确CI直接过不了，但是，swagger套装好像只提供了在线手工验证的方式。可以在找找有无其他工具。
使用方法:

http://host:port?url=swagger.json的地址

好了，现在根据swagger-php的文档，写一些注释看一下吧。