swagger2接口在线化文档的快速生成

1、简说

对于开发，尤其是前后端分离的情况下，后端工程师的接口文档就是一个很大的工作量。开发初期，接口变更快，自己的代码上修改了，还需要修改接口文档的设计，造成的结果就是，无端的增加了自己的工作量，这时候采用可视化，规范化的自动接口生成文档工具就比较重要了

2.1、jar的来源说明-github

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

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.0</version>
</dependency>

该jar的图形化界面设计比较优雅，看着符合文档范

一般的访问地址：http://ip:port/projectName/doc.html

2.2、jar的来源-Springfox

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

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

该界面就是一个流失的布局，格局感不是很强烈

一般的访问地址：http://ip:port/projectName/swagger-ui.html

3、springboot项目中采用的swagger2

由于是接口文档，不参与项目的多数配置，是单独的一套，所以配上与现有的项目配置接口不产生任何的影响，除非在项目接口涉及到了权限等的问题，在过滤器或者拦截器的时候，需要放开权限等的问题需要注意下。

该篇主要采用的是基于github的jar来实现的，接口文档的最后展示形式主要看个人喜好或者团队喜好决定。

3.1，swagger2的配置

pom引入依赖jar，就不多说了

配置文件类

swagger2的类主要内容

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class Swagger2 {
    //swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("测试工程类接口文档")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zh.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot API 测试")
                //创建人
                .contact(new Contact("：zh", "xxxx", "xxx@xxx.com"))
                //版本号
                .version("1.0.0")
                //描述
                .description("API 描述")
                .build();
    }
}

 

到这里，swagger的配置已经完成了，现在就需要去实现每一个controller中的接口的描述信息了

3.2、接口信息的添加

由于自己的测试工程较多接口，该篇展示其一：FileController

类内容为：

@Slf4j
@RestController
@RequestMapping(value = "/file")
@Api(tags = {"文件相关接口"})
public class FileController {

    @PostMapping(value = "/upload")
    @ApiOperation(value = "文件搬迁接口", notes = "不需要token")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "mainInfo", value = "券标题", dataType = "Long", paramType = "query"),
            @ApiImplicitParam(name = "activityId", value = "活动ID", dataType = "String", paramType = "query"),
            @ApiImplicitParam(name = "type", value = "类型:1：商场 2：商户 3：指定活动", dataType = "String", paramType = "query", required = true)
    })
    public Map<Object, Object> uploadFile(MultipartFile file) {
        //获取文件名称
        String fileName = file.getOriginalFilename();
        //文件存放路径
        String path = "E:\\img\\" + fileName;
        //上传文件
        File targetFile = new File(path);
        if (!targetFile.exists()) {
//            targetFile.mkdirs();// 这个方法是创建文件夹
            try {
                boolean newFile = targetFile.createNewFile();// 这个是创建文件
                if (newFile) {
                    File file1 = new File(path);
                    file.transferTo(file1);
                }
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
        System.out.println("文件上传成功");
        HashMap<Object, Object> map = new HashMap<>();
        return map;
    }

}

接口上的描述没有对应的匹配的写，只是展示可以这样写，当然也有其他的一些注解标签可用，此处就不一一展示

启动项目，地址栏输入地址：http://127.0.0.1:9100/demo-pro/doc.html

 

可以看到相关的接口文档已经生成。

由于自己的接口仅仅只是做博客写的需要，并没有做完善的接口描述，多多包涵，

以此就可以提供前端的接口文档地址形成，由于每个人只负责其中部分接口，更新完善也是很小的工作量，而且也不需要在找其他工具类进行接口文档的设计等。

该篇部分地方逻辑不是很严谨，仅仅做技术的分享。

一点一点的积累就是进步！！！！！