Swagger代码实战

什么是Swagger

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger API文档工具可以满足下列需求：

• 支持项目中的API接口自动生成同步的在线文档。
• 生成的API文档可用于项目内部API审核，查看等。
• 通过Swagger实时的API接口同步功能，方便测试人员和接口调用者动态了解API及其变化。
• 这些文档可作为客户产品文档的一部分进行发布。
• 支持API规范生成代码，生成的客户端和服务器端骨架代码可以加速开发和测试速度。

##常用到的注解有：

@Api ：用在类上，说明该类的作用
@ApiOperation ：用在方法上，说明方法的作用
@ApiImplicitParams ：用在方法上包含一组参数说明
@ApiImplicitParam ：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
    paramType：参数放在哪个地方
        header-->请求参数的获取：@RequestHeader
        query-->请求参数的获取：@RequestParam
        path（用于restful接口）-->请求参数的获取：@PathVariable
        body（不常用）
        form（不常用）
    name：参数名
    dataType：参数类型
    required：参数是否必须传
    value：参数的意思
    defaultValue：参数的默认值
@ApiResponses ：用于表示一组响应
@ApiResponse ：用在@ApiResponses中，一般用于表达一个错误的响应信息
    code：数字，例如400
    message：信息，例如"请求参数没填好"
    response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：描述一个model的属性

##@API注解：

用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = "/user", description = "Operations about user")

与Controller注解并列使用。 属性配置：

属性名称                 备注
value                  url的路径值("别用！！！会在url上显示该值")
tags                   如果设置这个值、value的值会被覆盖
description            对api资源的描述
basePath               基本路径可以不配置
position               如果配置多个Api 想改变显示的顺序位置
produces               For example, "application/json, application/xml"
consumes               For example, "application/json, application/xml"
protocols              Possible values: http, https, ws, wss.
authorizations         高级特性认证时配置
hidden                 配置为true 将在文档中隐藏

代码实战

控制器类

package com.demo.myjson.controller;

import com.demo.myjson.pojo.CreatePersonRequest;
import com.google.gson.Gson;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/person")
@Api(tags = "个人信息接口") //说明该类的作用
public class PersonController {
//    @ResponseBody //将controller的方法返回的对象通过适当的转换器转换为指定的格式之后，写入到response对象的body区，通常用来返回JSON数据或者是XML数据
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",paramType = "query",value = "用户名",required = true),
            @ApiImplicitParam(name = "age",paramType = "query",value = "年龄",required = true)
    })
    @ApiResponses({
            @ApiResponse(code = 401,message = "你没权限"),
            @ApiResponse(code = 403,message = "你被禁止访问了"),
            @ApiResponse(code = 404,message = "没找到，哈哈哈")
    })
    @ApiOperation("获取个人信息") //说明方法的作用
    @GetMapping("getInfo")
    public CreatePersonRequest getInfo(@RequestParam String name,@RequestParam Integer age){  //@RequestParam，用来直接获取URL中的参数
        CreatePersonRequest p = new CreatePersonRequest();
        p.setName(name);
        p.setAge(age);
        return p;
    }

    @ResponseBody
//    @ApiImplicitParam(name = "age",paramType = "body",value = "用户名",required = true)
    @ApiOperation("添加个人信息")
    @PostMapping("addInfo")
    public CreatePersonRequest addInfo(@RequestBody CreatePersonRequest person,@RequestBody Integer age){
        person.setName("hbl");
        person.setAge(18);
        person.setBirthday("19951003");
        return person;
    }

//    @ResponseBody
    @ApiOperation("更新个人信息")
    @PostMapping("updateInfo")
    public CreatePersonRequest updateInfo(@RequestBody CreatePersonRequest person){
        person.setName("hbl");
        person.setAge(19);
        person.setBirthday("19951003");
        return person;
    }

    @ApiOperation("删除个人信息")
    @PostMapping("deleteInfo")
    public boolean deleteInfo(@RequestBody CreatePersonRequest person){
        person.setName("hbl");
        person.setAge(18);
        person.setBirthday("19951003");
        if((getInfo("hbl",18) != null))
            return true;
        return false;
    }
}

Swagger配置类

package com.demo.myjson.SwaggerConfig;

import io.swagger.annotations.Api;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置类
 * 在与spring boot集成时，放在与Application.java同级的目录下。
 * 通过@Configuration注解，让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */
//@SpringBootApplication        //same as @Configuration+@EnableAutoConfiguration+@ComponentScan
@Configuration
@EnableSwagger2  //启动swagger注解
public class SwaggerConfig implements WebMvcConfigurer {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//api接口包扫描路径
                .paths(PathSelectors.any()) //可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("myJson API")  //设置文档的标题
                .description("我的demo") //设置文档的描述
                .termsOfServiceUrl("http://192.168.10.3/")
                .contact(new Contact("黄宝玲","","[email protected]"))
                .version("1.0")
                .build();
    }

//    @Override
//    public void addResourceHandlers(ResourceHandlerRegistry registry) {
//        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
//    }

}

接口上方的信息是在配置文件中设置的，我们主要看接口的信息，有点像restful API，最左边是请求类型，put、post、get等等，然后是url，再是描述。

在本地浏览器访问本地8080端口的swagger-ui.html:

接口详情，点击try it out编写信息:

点击excute执行:

可以看到请求头、URL、请求体、返回响应等信息: