springfox-swagger笔记

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

@Configuration
@EnableSwagger2 //开启swagger，自动生成文档
public class SwaggerConfig {
    //一个Docket是一个组，组的划分可以通过paths()或apis()来实现，组名称可以作为api搜索条件。组包含多个tags，tag可以包含多个api；
    @Bean
    public Docket api() {
        //apiInfo():配置文档描述
        //apis():api过滤规则，可以自定义为那些接口生成文档
        //useDefaultResponseMessages():是否使用默认的响应信息
        //paths()::可以根据请求路径过滤api
        //globalResponseMessage():：所有接口统一定义响应信息
        //produces(): 为所有接口设置响应类型
        //consumes():(): 为所有接口设置请求类型
        //protocols(): 为所有接口设置支持的协议
        //groupName（）：组名称
        //tags：设置标签
        Tag tag = new Tag("订单导出api", "订单相关导出api描述");
        ResponseMessage error = new ResponseMessageBuilder().code(500).message("系统异常").build();
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .globalResponseMessage(RequestMethod.GET, Lists.newArrayList(error))
                .apiInfo(apiInfo())
                .groupName("订单导出api")
                .protocols(Sets.newHashSet("http", "https"))
                .consumes(Sets.newHashSet(MediaType.APPLICATION_JSON_VALUE))
                .produces(Sets.newHashSet(MediaType.APPLICATION_JSON_VALUE))
                .tags(tag)
                .select()
                .apis((RequestHandlerSelectors.basePackage("com.zhen.export"))
                        .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        //title:文档标题
        //description：文档的描述
        //termsOfServiceUrl:文档的服务条款说明网址
        //version:版本号
        //contact：文档的联系人信息
        //license:文档版权信息
        //licenseUrl:版权信息超链接
        return new ApiInfoBuilder()
                .title("珍品导出系统API文档")
                .description("珍品导出系统API文档")
                .contact(new Contact("moon", "www.baidu.com", "moon@zhen.com"))
                .license("license-moon").
        .licenseUrl:
        版权信息超链接("license-moon-url")
                .termsOfServiceUrl("http://www.zhen.com").version("2.0").build();
    }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

@RestController
@RequestMapping("/orders")
@Api(tags = "订单导出api")
public class OrderExportController {
    @ApiOperation(value = " 订单导出任务-对象请求", notes = "订单导出任务详细描述", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "test", value = "测试字段", required = true, dataType = "String")
    })
    @ApiResponses({
            @ApiResponse(code = 500, message = "系统异常")
    })
    @RequestMapping(value = "/doExportTaskToOperationOnObject.json", method = RequestMethod.GET)
    public EgResponse doExportTaskToOperationOnObject(OrderDetailRequest req,
                                                      @ApiIgnore String test, HttpServletRequest request) throws Exception {
        return EgResponse.success(new OrderInfo());
    }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

public class OrderDetailRequest {
    @ApiModelProperty(value = "平台编码", required = true, example = "70")
    private String platformCode;

    @ApiModelProperty(value = "平台订单号", required = true, example = "sn20201029")
    private String platformOrderSn;

    @ApiModelProperty(value = "订单状态", example = "0", allowableValues = "0,1,2,3,4")
    private Integer status;

    @ApiModelProperty(value = "特殊字段", example = "0", hidden = true)
    private BigDecimal special;

    @ApiModelProperty(value = "开始时间 格式：yyyy-MM-dd HH:mm:ss")
    private String startTime;
}

@ApiModel(value = "response", description = "用于通用响应")
public class EgResponse {
    @ApiModelProperty(value = "响应码", example = "200")
    private String code;

    @ApiModelProperty(value = "响应码描述", example = "成功")
    private String message;

    @ApiModelProperty("响应数据")
    private T data;
}

1
2
3
4
5
6
7
8

    @ApiOperation(value = "通过站点id查询栏目列表")
    @Deprecated
    @RequestMapping(value = "findByTerminalId", method = RequestMethod.POST)
    public AjaxResponse<SelectOutputBean<AppNavigationInternalOutputBean>> findByTerminalId(
            @RequestBody @Validated @ApiParam(required = true) ConditionOfSiteModel model) {
        SelectOutputBean<AppNavigationInternalOutputBean> result = getService().findByTerminalId(model);
        return AjaxResponse.success(result);
   }