springboot日记之初入swag

## 什么是swag？
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。简单来说，可以更友好的展示自己对外的API，调用、测试更加方便、轻松。
下面的操作都是以maven构建的springboot项目为基础。

首先要做的就是引入swag的jar包

		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger2</artifactId>
		    <version>2.5.0</version>
		</dependency>

配置config类

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
        // 为当前包路径
                .apis(RequestHandlerSelectors.basePackage("learn.controller")).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
        // 页面标题
                .title("练手搭建springboot项目")
                // 创建人
                // .contact(new Contact("ljg", "http://blog.bianxh.top/", ""))
                // 版本号
                .version("1.0")
                // 描述
                .description("API 描述").build();
    }
}

注解需要暴露的接口

@Api(value = "用户", tags = { "用户操作接口" })
@RestController
@RequestMapping(value = "/login")
public class LoginController {
    @Autowired
    private IUserInfoService userInfoService;
    @Autowired
    private ILoginService loginService;

    /**
     * 登陆入口
     * @Author ljg 2020年2月6日 上午12:06:32
     * @return
     */
    @ApiOperation(value = "登陆入口", notes = "登陆逻辑")
    @RequestMapping(value = "/", method = RequestMethod.POST)
    @ResponseBody
    public RestResponse<String> login(@RequestBody UserInfoCond userInfoCond) {
        RestResponse<String> response = null;
        try {
            response = RestResposeUtil.createResponse(RestCode.SUCCESS, loginService.login(userInfoCond));
        } catch (Exception e) {
            response = ExceptionHandleUtil.handle(e);
        }
        return response;
    }
}

4.注解实体

@Data
@ApiModel(value = "userInfoCond", description = "查询条件实体")
public class UserInfoCond implements Serializable {

    /**
     * 序列化ID
     */

    private static final long serialVersionUID = 1L;
    /**
     * 用户id
     */
    @ApiModelProperty(value = "用户ID", required = false)
    private String userId;
    /**
     * 用户名字
     */
    @ApiModelProperty(value = "用户名字", required = true)
    private String userName;
    /**
     * 密码
     */
    @ApiModelProperty(value = "用户密码", required = true)
    private String passWord;
}

操作完以上步骤，启动项目。
使用swag可视地址访问：http://localhost:8080/swagger-ui.html#/
在这里插入图片描述

swag常用注解
@Api：用在类上，说明该类的作用
例如：@Api(value = “登陆服务”, tags = { “登陆操作接口” })
@ApiOperation：用在方法上，注解来给API增加方法说明。
例如： @ApiOperation(value = “登陆入口”, notes = “登陆逻辑”)
@ApiImplicitParams : 用在方法上包含一组参数说明，搭配ApiImplicitParam使用。
@ApiImplicitParam：用在方法上包含一个参数说明
注意：@ApiImplicitParam的参数说明：
|paramType：指定参数放在哪个地方|header：请求参数放置于Request Header，使用@RequestHeader获取
query：请求参数放置于请求地址，使用@RequestParam获取
path：（用于restful接口）–>请求参数的获取：@PathVariable
body：（不常用）
form（不常用） |
|name：参数名|–|
| dataType：参数类型| |
|required：参数是否必须传| true | false|
|-value：说明参数的意思-|–|
| defaultValue：参数的默认值| |
注意：在后台采用对象接收参数时，Swagger自带的工具采用的是JSON传参，测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。
@ApiModel：用在实体上，用来描述一个实体
@ApiModelProperty：用在实体的属性上，用来描述这个属性
以上就是我本次练习所用到的，想要深入了解请参考更多微博

参考
http://blog.didispace.com/springbootswagger2/
http://blog.csdn.net/jia20003/article/details/50700736
Swagger官网：http://swagger.io/
Spring Boot & Swagger UI ： http://fruzenshtein.com/spring-boot-swagger-ui/

来源：CSDN

作者：lingjianqwert110

链接：https://blog.csdn.net/lingjianqwert110/article/details/104827088

标签

swag

restful框架

swagger

可视化