Swagger文档使用

有很多人不清楚swagger ui的路径，由于我们使用了更为好用的swagger-bootstrap-ui，实际上使域名+端口 +/doc.html，如：http://localhost:8080/doc.html

在没有Swagger之前，我们需要自己手写文档，手写文档的出现问题：

文档更新时需要要与前端人员进行对接，文档存在更新不及时
接口文档多，没有进行分组管理，增加管理难度
不能直接在线接口调试，通常需要借助工具（如postman）,效率大大降低
接口说明与返回结果不明确

而通过swagger就能轻松解决这些问题，而且spirngboot整合swagger也相对简单

添加依赖

 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>1.9.3</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>2.9.2</version>
</dependency>

添加配置类并开启

在yami-shop-api工程中的config文件下，有swagger相应的配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    
    

     @Bean
     public Docket baseRestApi() {
    
    
         return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .groupName("基础版")
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.yami.shop.api"))
         .paths(PathSelectors.any())
         .build();
     }
     @Bean
     public ApiInfo apiInfo() {
    
    
         return new ApiInfoBuilder()
         .title("商城接口文档")
         .description("简介")
         .termsOfServiceUrl("服务Url")
         .contact(new Contact("作者","服务Url", ""))
         .version("1.0")
         .build();
     }
}

特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口

apis(RequestHandlerSelectors.basePackage("com.yami.shop.api"))

用@Configuration注解该类，让spring托管这个类，@Bean标注方法等价于XML中配置bean

用@EnableSwagger2标识要开启Swagger2

接口使用

在配置好之后，我们就可以对swagger进行使用,比如在AreaController类中

@RestController
@RequestMapping("/p/area")
@Api(tags="省市区接口")
public class AreaController {
    
    

    @Autowired
    private AreaService areaService;
    
    @GetMapping("/listByPid")
    @ApiOperation(value="获取省市区信息", notes="根据省市区的pid获取地址信息")
    @ApiImplicitParam(name = "pid", value = "省市区的pid(pid为0获取所有省份)", required = true, dataType = "String")
    public ResponseEntity<List<Area>> listByPid(Long pid){
    
    
        List<Area> list = areaService.listByPid(pid);
        return ResponseEntity.ok(list);
    }
}

@Api(tags="省市区接口")定义标签分组接口，在这个类下定义的所有接口将位于这个标签之下

@ApiOperation()定义具体的接口标题信息，notes可以为这个标签添加注释

@ApiImplicitParam()对应的参数列表信息，用户告诉前端开发人员，这个接口需要传递什么参数及参数的说明

如有多个参数需要说明，可使用@ApiImplicitParams()下面可包含多个@ApiImplicitParam()

实体类

@Data
@TableName("tz_area")
public class Area implements Serializable {
    
    
    private static final long serialVersionUID = -6013320537436191451L;
    @TableId
    @ApiModelProperty(value = "地区id",required=true)
    private Long areaId;

    @ApiModelProperty(value = "地区名称",required=true)
    private String areaName;

    @ApiModelProperty(value = "地区上级id",required=true)
    private Long parentId;

    @ApiModelProperty(value = "地区层级",required=true)
    private Integer level;

    @TableField(exist=false)
    private List<Area> areas;
}

@ApiModelProperty()利用这个注解可以告诉前端开发人员该字段代表的含义

常用注解

注解	作用
@Api	修饰整个类，描述Controller的作用
@ApiOperation	描述一个类的一个方法，或者说一个接口
@ApiParam	单个参数描述
@ApiModel	用对象来接收参数
@ApiProperty	用对象接收参数时，描述对象的一个字段
@ApiResponse	HTTP响应其中1个描述
@ApiResponses	HTTP响应整体描述
@ApiIgnore	使用该注解忽略这个API
@ApiError	发生错误返回的信息
@ApiImplicitParam	一个请求参数
@ApiImplicitParams	多个请求参数

分页参数的文档以及关于swagger文档的骚操作

我们仔细留意swagger文档，可以发现 swagger文档返回接口数据的url为：/v2/api-docs 。这个url被 springfox.documentation.swagger2.web.Swagger2Controlle#getDocumentation() 关联。通过jsonSerializer.toJson(swagger) 生成特定的json文档。

当我们使用PageParam<T> 这个分页参数生成文档的时候，总是会返回泛型里面的对象信息，我们根据无论使用@ApiParam(hidden = true) 又或者是 @JsonIgnore 都无效，所以我们可以修改自己的jsonSerializer生成的响应的json

自定义Swagger 的序列化，去除分页参数中的records值

public class SpringfoxJsonSerializer extends JsonSerializer {
    
    

    public SpringfoxJsonSerializer(List<JacksonModuleRegistrar> modules) {
    
    
        super(modules);
    }

    @Override
    public Json toJson(Object toSerialize) {
    
    
        if (!(toSerialize instanceof Swagger)) {
    
    
            return super.toJson(toSerialize);
        }
        Swagger swagger = (Swagger)toSerialize;

        swagger.getPaths().forEach((key, path) ->{
    
    
            Operation get = path.getGet();
            if (get != null) {
    
    

                List<Parameter> parameters = get.getParameters();
                if (parameters != null) {
    
    
                    parameters.removeIf(parameter -> parameter.getName().startsWith("records[0]."));
                }
            }
        });

        return super.toJson(swagger);
    }
}

新序列化的bean

@Configuration
public class SpringFoxJsonSerializerConfig {
    
    

    @Bean
    @Primary
    public JsonSerializer yamiSpringfoxJsonSerializer(List<JacksonModuleRegistrar> moduleRegistrars) {
    
    
        return new SpringfoxJsonSerializer(moduleRegistrars);
    }
}

添加依赖

添加配置类并开启

接口使用

实体类

常用注解

分页参数的文档以及关于swagger文档的骚操作

猜你喜欢