前言

之前一直用的是showDoc做的接口文档梳理,表示文档书写起来也是很麻烦的一件事情,之后看了一下swagger,觉得非常好用,那么接下来先了解一下swagger的使用吧.

参考:

https://blog.csdn.net/xupeng874395012/article/details/68946676
https://www.cnblogs.com/fengli9998/p/7522973.html

Swagger 是啥?

简单说下，它的出现就是为了方便进行测试后台的restful形式的接口，实现动态的更新，当我们在后台的接口修改了后，swagger可以实现自动的更新，而不需要人为的维护这个接口进行测试自动化接口文档书写。

java的swagger应用

**
环境: java8
框架:springBoot (2.0.4.RELEASE)
Swagger:2.2.2
**

配置项

添加pom.xml的依赖配置

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

2.添加swagger的配置文件

该配置文件是一个java类,需要与启动类文件放置于同一个目录,内容如下:

Swagger 接口文档

package com.example.demo;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) //确定文档输出的目录范围
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("spring boot 结合swagger2 的测试") //标题
                .contact("ZZT")//作者
                .version("v1.0.0")//版本
                .description("描述用中文试一下！！！") //描述
                .build();
    }


}

API书写说明:

DEMO:

package com.example.demo.controller;

import com.example.demo.mapper.UsersMapper;
import com.example.demo.model.Users;
import io.swagger.annotations.*;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;
import java.util.Map;

@RestController
@MapperScan("com.example.demo.mapper")
@Api("一个控制器的相关配置") //控制器大分类的标题说明
public class UsersController {

    @Autowired
    public UsersMapper usersMapper;

    @ApiOperation(value = "查询所有信息",notes = "查询数据库中的某个信息") //接口标题
    @RequestMapping(value = "/user",method = RequestMethod.GET)//需要注明method,否则接口文档会给出全部的类型(PUT,DELETE,POST,GET等等)
    public List<Users> getUser(){
        List<Users> users = usersMapper.getAllUsers();
        return  users;
    }


    @ApiOperation(value = "新增用户信息",notes = "提交用户信息，自增id")//接口标题
    @ApiResponses({
            @ApiResponse(code = 200, message = "操作成功"),
            @ApiResponse(code = 500, message = "服务器内部异常"),
            @ApiResponse(code = 403, message = "权限不足")
    })//返回响应码
    @ApiImplicitParams({
            @ApiImplicitParam(name = "age",value = "36",paramType ="query",dataType = "Intger",required=true),
            @ApiImplicitParam(name = "name",value = "defaultName",paramType ="query",dataType = "String",required=true),
            @ApiImplicitParam(name = "title",value = "defaultTitle",paramType ="query",dataType = "String",required=true),
    })//地址栏参数说明
    @RequestMapping(path = "/user/post",method = RequestMethod.POST)//需要注明method,否则接口文档会给出全部的类型(PUT,DELETE,POST,GET等等)
    public Integer insertUser(@RequestBody Users user){//请求body的规范,这里的字段设置还没搞明白
                return usersMapper.insertSelective(user);
    }


    @RequestMapping(path = "/user/edit",method = RequestMethod.POST)
    public Integer updateUser(@RequestBody Map<String,String> params ){
        Integer id = Integer.parseInt(params.get("id"));
        Users user = usersMapper.selectByPrimaryKey(id);
        user.setTitle("update test");
        return usersMapper.updateByPrimaryKey(user);
    }

}

说明:

作用范围	API	使用位置
对象属性	@ApiModelProperty	用在出入参数对象的字段上
协议集描述	@Api	用于controller类上
协议描述	@ApiOperation	用在controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

@ApiImplicitParam 说明:

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交仅支持POST
dataType		参数的数据类型只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

访问:

http://localhost:8080/swagger-ui.html

Swagger 接口文档

PHP的swagger应用


<?php
/**
 * Created by PhpStorm.
 * User: ZZT
 * Date: 18-5-16
 * Time: 下午4:23
 */

namespace App\Http\Controllers;

use Log;

/**
 * Class FileController
 * @package App\Http\Controllers
 *
 * @OA\OpenApi(
 *     @OA\Server(
 *      url="http://www.workec.com",
 *      description="完整的接口用例"
 *     ),
 *      @OA\Info(
 *     version="1.0.0",
 *     title="swagger 文档信息",
 *     description="描述信息",
 *     @OA\Contact(name="联系我们"),
 *     @OA\License(name="MIT")
 *      )
 * )
 *
 *
 */

/**
 * @OA\Parameter(
 *   parameter="xsrf-token",
 *   name="x-xsrf-token",
 *   description="头部校验信息,post数据必须存在该头部校验信息",
 *   @OA\Schema(
 *     type="string",
 *   ),
 *   in="header",
 *   required=true
 * )


/**
 * @OA\Schema(
 *     schema="ErrorModel",
 *     required={"code", "message"},
 *     @OA\Property(
 *         property="code",
 *         type="integer",
 *         format="int32"
 *     ),
 *     @OA\Property(
 *         property="message",
 *         type="string"
 *     )
 * )
 */

/**
 *  @OA\Schema(
 *   schema="PostBody",
 *   type="object",
 *   required={"id"},
 *   @OA\Property(property="id",  type="integer"),
 *   @OA\Property(property="name",  type="string"),
 *   @OA\Property(property="title", type="string")
 *       )
 */


/**
 * @OA\Tag(name="A",description="ceshiA")
 */

/**
 * @OA\Tag(name="B",description="ceshiB")
 */

/**
 * @OA\Tag(name="C",description="ceshiC")
 */

class FileController extends Controller
{
    public function upload(){
        $files = $_FILES['data'];
        $content = file_get_contents($files['tmp_name']);
        file_put_contents(storage_path('file/').$_POST['name'],$content,FILE_APPEND);
    }

    public function index(){
        return view('file.index');
    }

    /**
     * @OA\Post(
     *     path="/example",
     *     summary="这是一个example",
     *     tags={"A"},
     *     @OA\RequestBody(
     *         description="这里是请求体的描述信息",
     *         required=true,
     *         @OA\JsonContent(ref="#/components/schemas/PostBody")
     *     ),
     *     @OA\Parameter(ref="#/components/parameters/xsrf-token"),
     *     @OA\Response(
     *         response=200,
     *         description="OK"
     *     )
     * )
     */
    public function example(){
        echo "example","hahahah";
    }
}