Skip to content

Commit 451dce6

Browse files
YurunsoftYurunsoft
committed
Merge branch 'dev'
2 parents 03f8d77 + e3701c6 commit 451dce6

File tree

13 files changed

+654
-677
lines changed

13 files changed

+654
-677
lines changed

‎LICENSE

+21-21
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
1-
MIT License
2-
3-
Copyright (c) 2019 imi 开发组
4-
5-
Permission is hereby granted, free of charge, to any person obtaining a copy
6-
of this software and associated documentation files (the "Software"), to deal
7-
in the Software without restriction, including without limitation the rights
8-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9-
copies of the Software, and to permit persons to whom the Software is
10-
furnished to do so, subject to the following conditions:
11-
12-
The above copyright notice and this permission notice shall be included in all
13-
copies or substantial portions of the Software.
14-
15-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21-
SOFTWARE.
1+
MIT License
2+
3+
Copyright (c) 2019 imi 开发组
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+165-163
Original file line numberDiff line numberDiff line change
@@ -1,163 +1,165 @@
1-
# imi-apidoc
2-
3-
[![Latest Version](https://img.shields.io/packagist/v/imiphp/imi-apidoc.svg)](https://packagist.org/packages/imiphp/imi-apidoc)
4-
[![Php Version](https://img.shields.io/badge/php-%3E=7.1-brightgreen.svg)](https://secure.php.net/)
5-
[![Swoole Version](https://img.shields.io/badge/swoole-%3E=4.4.0-brightgreen.svg)](https://github.com/swoole/swoole-src)
6-
[![IMI License](https://img.shields.io/github/license/imiphp/imi-apidoc.svg)](https://github.com/imiphp/imi-apidoc/blob/master/LICENSE)
7-
8-
## 介绍
9-
10-
支持在项目中使用 Swagger 注解语法，运行命令，生成 Swagger 文件。
11-
12-
Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。
13-
14-
Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。
15-
16-
Swagger 是一种通用的，和编程语言无关的 API 描述规范。
17-
18-
imi-apidoc 基于 [zircote/swagger-php](https://github.com/zircote/swagger-php) 开发，100% 支持写法。
19-
20-
## Composer
21-
22-
本项目可以使用composer安装，遵循psr-4自动加载规则，在你的 `composer.json` 中加入下面的内容:
23-
24-
```json
25-
{
26-
"require": {
27-
"imiphp/imi-apidoc": "^1.0.0"
28-
}
29-
}
30-
```
31-
32-
然后执行 `composer update` 安装。
33-
34-
## 使用说明
35-
36-
> 可以参考 `example`、`tests` 目录示例。
37-
38-
项目配置文件：
39-
40-
```php
41-
[
42-
'components' => [
43-
'ApiDoc' => 'Imi\ApiDoc',
44-
],
45-
]
46-
```
47-
48-
Swagger 书写文档说明：<https://zircote.github.io/swagger-php/Getting-started.html#annotation-placement>
49-
50-
**Demo:**
51-
52-
```php
53-
<?php
54-
namespace ImiApp\ApiServer\Controller;
55-
56-
use Imi\Server\Route\Annotation\Route;
57-
use Imi\Server\Route\Annotation\Action;
58-
use Imi\Controller\SingletonHttpController;
59-
use Imi\Server\Route\Annotation\Controller;
60-
61-
/**
62-
* @OA\Info(title="My First API", version="0.1")
63-
* @Controller("/")
64-
*/
65-
class IndexController extends SingletonHttpController
66-
{
67-
/**
68-
* @Action
69-
* @Route("/")
70-
*
71-
*
72-
* @return void
73-
*/
74-
public function index()
75-
{
76-
77-
}
78-
79-
/**
80-
* @Action
81-
* @Route(url="login", method="POST")
82-
*
83-
* @param string $username 用户名
84-
* @param integer $password 密码
85-
*
86-
* @return void
87-
*/
88-
public function login(string $username, int $password)
89-
{
90-
91-
}
92-
93-
/**
94-
* @Action
95-
* @Route("register")
96-
* @OA\Get(
97-
* path="/register",
98-
* @OA\Response(response="200", description="An example resource")
99-
* )
100-
*
101-
* @param string $username 用户名
102-
* @param integer $password 密码
103-
* @param string $birthday 生日
104-
*
105-
* @return void
106-
*/
107-
public function register(string $username, int $password
108-
, string $birthday)
109-
{
110-
111-
}
112-
113-
/**
114-
* @Action
115-
*
116-
* @param int $id
117-
* @return void
118-
*/
119-
public function get(int $id)
120-
{
121-
122-
}
123-
124-
}
125-
```
126-
127-
imi-apidoc 会根据 `@Route` 注解、`@param` 注释，自动补足相关信息。让你不必为每个接口都书写 Swagger 注解，提升开发效率。
128-
129-
当然，如果希望更加个性化的信息设置，还是要自己去书写的！
130-
131-
**生成命令：**
132-
133-
Yaml 格式: `imi doc/api -to api.yml`
134-
135-
Json 格式: `imi doc/api -to api.json`
136-
137-
指定扫描的命名空间：`imi doc/api -to api.json -namespace "ImiApp\Controller1,ImiApp\Controller2"`
138-
139-
**效果：**
140-
141-
<img src="https://raw.githubusercontent.com/imiphp/imi-apidoc/master/res/1.jpg"/>
142-
143-
<img src="https://raw.githubusercontent.com/imiphp/imi-apidoc/master/res/2.jpg"/>
144-
145-
## 免费技术支持
146-
147-
QQ群：17916227 [![点击加群](https://pub.idqqimg.com/wpa/images/group.png "点击加群")](https://jq.qq.com/?_wv=1027&k=5wXf4Zq)，如有问题会有人解答和修复。
148-
149-
## 运行环境
150-
151-
- [PHP](https://php.net/) >= 7.1
152-
- [Composer](https://getcomposer.org/)
153-
- [Swoole](https://www.swoole.com/) >= 4.3.0
154-
155-
## 版权信息
156-
157-
`imi-apidoc` 遵循 MIT 开源协议发布，并提供免费使用。
158-
159-
## 捐赠
160-
161-
<img src="https://raw.githubusercontent.com/imiphp/imi-apidoc/master/res/pay.png"/>
162-
163-
开源不求盈利，多少都是心意，生活不易，随缘随缘……
1+
# imi-apidoc
2+
3+
[![Latest Version](https://img.shields.io/packagist/v/imiphp/imi-apidoc.svg)](https://packagist.org/packages/imiphp/imi-apidoc)
4+
[![Php Version](https://img.shields.io/badge/php-%3E=7.1-brightgreen.svg)](https://secure.php.net/)
5+
[![Swoole Version](https://img.shields.io/badge/swoole-%3E=4.4.0-brightgreen.svg)](https://github.com/swoole/swoole-src)
6+
[![IMI License](https://img.shields.io/github/license/imiphp/imi-apidoc.svg)](https://github.com/imiphp/imi-apidoc/blob/master/LICENSE)
7+
8+
## 介绍
9+
10+
支持在项目中使用 Swagger 注解语法，运行命令，生成 Swagger 文件。
11+
12+
Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。
13+
14+
Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。
15+
16+
Swagger 是一种通用的，和编程语言无关的 API 描述规范。
17+
18+
imi-apidoc 基于 [zircote/swagger-php](https://github.com/zircote/swagger-php) 开发，100% 支持写法。
19+
20+
> 本仓库仅用于浏览，不接受 issue 和 Pull Requests，请前往：<https://github.com/Yurunsoft/imi>
21+
22+
## Composer
23+
24+
本项目可以使用composer安装，遵循psr-4自动加载规则，在你的 `composer.json` 中加入下面的内容:
25+
26+
```json
27+
{
28+
"require": {
29+
"imiphp/imi-apidoc": "^1.0.0"
30+
}
31+
}
32+
```
33+
34+
然后执行 `composer update` 安装。
35+
36+
## 使用说明
37+
38+
> 可以参考 `example`、`tests` 目录示例。
39+
40+
项目配置文件：
41+
42+
```php
43+
[
44+
'components' => [
45+
'ApiDoc' => 'Imi\ApiDoc',
46+
],
47+
]
48+
```
49+
50+
Swagger 书写文档说明：<https://zircote.github.io/swagger-php/Getting-started.html#annotation-placement>
51+
52+
**Demo:**
53+
54+
```php
55+
<?php
56+
namespace ImiApp\ApiServer\Controller;
57+
58+
use Imi\Server\Route\Annotation\Route;
59+
use Imi\Server\Route\Annotation\Action;
60+
use Imi\Controller\SingletonHttpController;
61+
use Imi\Server\Route\Annotation\Controller;
62+
63+
/**
64+
* @OA\Info(title="My First API", version="0.1")
65+
* @Controller("/")
66+
*/
67+
class IndexController extends SingletonHttpController
68+
{
69+
/**
70+
* @Action
71+
* @Route("/")
72+
*
73+
*
74+
* @return void
75+
*/
76+
public function index()
77+
{
78+
79+
}
80+
81+
/**
82+
* @Action
83+
* @Route(url="login", method="POST")
84+
*
85+
* @param string $username 用户名
86+
* @param integer $password 密码
87+
*
88+
* @return void
89+
*/
90+
public function login(string $username, int $password)
91+
{
92+
93+
}
94+
95+
/**
96+
* @Action
97+
* @Route("register")
98+
* @OA\Get(
99+
* path="/register",
100+
* @OA\Response(response="200", description="An example resource")
101+
* )
102+
*
103+
* @param string $username 用户名
104+
* @param integer $password 密码
105+
* @param string $birthday 生日
106+
*
107+
* @return void
108+
*/
109+
public function register(string $username, int $password
110+
, string $birthday)
111+
{
112+
113+
}
114+
115+
/**
116+
* @Action
117+
*
118+
* @param int $id
119+
* @return void
120+
*/
121+
public function get(int $id)
122+
{
123+
124+
}
125+
126+
}
127+
```
128+
129+
imi-apidoc 会根据 `@Route` 注解、`@param` 注释，自动补足相关信息。让你不必为每个接口都书写 Swagger 注解，提升开发效率。
130+
131+
当然，如果希望更加个性化的信息设置，还是要自己去书写的！
132+
133+
**生成命令：**
134+
135+
Yaml 格式: `imi doc/api -to api.yml`
136+
137+
Json 格式: `imi doc/api -to api.json`
138+
139+
指定扫描的命名空间：`imi doc/api -to api.json -namespace "ImiApp\Controller1,ImiApp\Controller2"`
140+
141+
**效果：**
142+
143+
<img src="https://raw.githubusercontent.com/imiphp/imi-apidoc/master/res/1.jpg"/>
144+
145+
<img src="https://raw.githubusercontent.com/imiphp/imi-apidoc/master/res/2.jpg"/>
146+
147+
## 免费技术支持
148+
149+
QQ群：17916227 [![点击加群](https://pub.idqqimg.com/wpa/images/group.png "点击加群")](https://jq.qq.com/?_wv=1027&k=5wXf4Zq)，如有问题会有人解答和修复。
150+
151+
## 运行环境
152+
153+
- [PHP](https://php.net/) >= 7.1
154+
- [Composer](https://getcomposer.org/)
155+
- [Swoole](https://www.swoole.com/) >= 4.3.0
156+
157+
## 版权信息
158+
159+
`imi-apidoc` 遵循 MIT 开源协议发布，并提供免费使用。
160+
161+
## 捐赠
162+
163+
<img src="https://cdn.jsdelivr.net/gh/Yurunsoft/IMI@dev/res/pay.png"/>
164+
165+
开源不求盈利，多少都是心意，生活不易，随缘随缘……

0 commit comments

Comments
 (0)