swagger 优雅的解决了这个问题。它是一个功能强大的API框架，它的集成非常简单，不仅提供了在线文档的查阅，而且还提供了在线文档的测试。swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。swagger 让部署管理和使用功能强大的 API 从未如此简单。

1、maven集成swagger

最近版本可去中央仓库 查询
https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui

<!-- swagger组件 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
<!-- swagger美化组件 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

2、config配置

package com.riskeys.heb.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;


@EnableSwagger2
@Configuration
class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("哈尔滨项目接口管理") //指定分组，对应(/v2/api-docs?group=)
                .pathMapping("") //base地址，最终会拼接Controller中的地址
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
//                .apis(RequestHandlerSelectors.any())
//扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.riskeys.heb"))
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("哈尔滨项目接口文档")
                //创建人
                .contact(new Contact("xiuxian.wang", "",""))
                //版本号
                .version("1.0")
                //描述
                .description("接口说明文档")
                .build();
    }
}

3、web配置中释放静态资源

 @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

4、注解使用

1）常用注解
@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam 一个参数

@ApiImplicitParams 多个参数、

2）代码示例

@Slf4j
@RestController
@RequestMapping("/business")
@Api(value = "BusinessController",tags = "业务相关接口")//用于类
public class BusinessController {


    @PostMapping(value = "/rescue/download")
    @ApiOperation("救助计划")//用于方法
    public void rescuePlan(@RequestBody @Valid RescuePlanDto dto, HttpServletRequest request, HttpServletResponse response) {

        log.info("rescue pdf request info is :{}",JSONObject.toJSONString(dto));
        PdfReader reader;
        OutputStream os = null;
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        PdfStamper stamper;
}

@Data
public class RescuePlanDto {

    @NotBlank(message = "工单id不能为空")
    @ApiModelProperty(value = "工单id",required = true)//用于字段说明及必传性说明
    private String workId;//工单id
    @NotBlank(message = "救助类型不能为空")
    @ApiModelProperty(value = "救助类型",required = true)
    private String type;//救助类型

}

5、启动项目访问接口管理平台

1、美化版平台路径http://{ip}:{port}/doc.html

91ZXQEZGFAN()(%V_7_}29E.png

WEW9HCKN3WEH49S1PX3PWIK.png

6、文档输出

点击拷贝文档并粘贴至可编辑markdown文件编辑器中(Typora),即可导出pdf各种格式

0_%QCS97XRL8D$Z@(G`N7U9.png