spring boot生成cvs文件 springboot自动生成api文档

转载

风轻云淡的开发 2023-07-28 15:38:40

文章标签 spring boot生成cvs文件 java json postman spring 文章分类 spring boot 后端开发

引言

　　在做服务端开发的时候，难免会涉及到API 接口文档的编写，可以经历过手写API 文档的过程，就会发现，一个自动生成API文档可以提高多少的效率。

　　以下列举几个手写API 文档的痛点：

文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
接口返回结果不明确
不能直接在线测试接口，通常需要使用工具，比如postman
接口文档太多，不好管理

　　Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

配置 Swagger

　　1. 修改pom.xml文件，添加依赖

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

　　2. 添加Swagger2的配置文件Swagger2Config

package com.springboot.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.springboot.controller")) //需要注意的是这里要写入控制器所在的包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

　　如上代码所示，通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

　　createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

　　添加文档内容

　　在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

spring boot生成cvs文件 springboot自动生成api文档_spring boot生成cvs文件

spring boot生成cvs文件 springboot自动生成api文档_postman_02

package com.springboot.controller;

import com.github.pagehelper.PageInfo;
import com.springboot.entity.Church;
import com.springboot.service.ChurchService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@Api(value = "团契操作controller", description = "团契相关的操作", tags = {"团契模块校验接口"})
@RestController
@RequestMapping("/church")
public class ChurchController {
    @Autowired
    private ChurchService churchService;

    @ApiOperation(value = "获取指定团契信息", notes = "根据传入标识获取详细信息")
    @ApiImplicitParam(name = "churchId", value = "团契标识", required = true, dataType = "String", paramType = "path")
    @RequestMapping(value = "/get/{churchId}", method = RequestMethod.GET, produces = {"application/json;charset=UTF-8"})
    public String getChurch(@PathVariable String churchId) {
        Church church = churchService.get(churchId);
        return church.toString();
    }

    @ApiOperation(value = "获取团契列表", notes = "获取团契列表")
    @RequestMapping(value = "list", method = RequestMethod.GET, produces = {"application/json;charset=UTF-8"})
    public List<Church> list() {
        return churchService.list();
    }

    @ApiOperation(value = "分页获取团契列表", notes = "获取团契列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "page", value = "第几页", required = true, dataType = "Integer", paramType = "path"),
            @ApiImplicitParam(name = "pageSize", value = "每页取几条记录", required = true, dataType = "Integer", paramType = "path")
    })
    @RequestMapping(value = "/list/{page}/{pageSize}", method = RequestMethod.GET, produces = {"application/json;charset=UTF-8"})
    public PageInfo<Church> list(@PathVariable("page") int page, @PathVariable("pageSize") int pageSize) {
        return churchService.list(page, pageSize);
    }
}

View Code