SpringBoot&Swagger构建REST API并生成API文档

一、理论基础

Swagger是什么??
背景:
现在的网站架构基本都由原来的后端渲染,
变成了:前端渲染、先后端分离的形态.

前后端交互的方式:api接口
api文档是提升开发效率

而swagger就是一款让你更好的书写API文档的框架。

没有swagger之前文档都是手写api,有写在confluence上,也有在readme里的。文档书写工具加多,而swagger拥有更好的支持。

特点

功能丰富 :支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
及时更新 :开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
整合简单 :通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。

同类型产品:轻量级rap 开发者阿里巴巴rap的github地址

二、swagger生态使用图

这部分可以快速了解下
这里写图片描述
简单描述下红颜色的是swaggger官网方推荐的。
1.swagger-ui
用来显示API文档的。添加ui的pom就可以获得一个简单的视图
这里写图片描述

点一个controller进去能够看到具体方法
这里写图片描述

2.swagger-editor
就是一个在线编辑文档说明文件(swagger.json或swagger.yaml文件)的工具,以方便生态中的其他小工具(swagger-ui)等使用。
在编辑器,左边编辑,右边立马就显示出编辑自己想要的效果出来。
这里写图片描述
编辑swagger说明文件使用的是yaml语法格式。具体的使用可以在官网查看https://swagger.io/

补充:各种语言版本的根据annotation或者注释生成swagger说明文档的工具,也就是说它扩语言。

目前最流行的做法,就是在代码注释中写上swagger相关的注释,然后,利用小工具生成swagger.json或者swagger.yaml文件。

3.swagger-validator

这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单,只需url地址栏,根路径下加上一个参数url,参数内容是放swagger说明文件的地址。即可校验。

这里写图片描述
docker hub地址为:https://hub.docker.com/r/swaggerapi/swagger-validator/

4.swagger-codegen

代码生成器,脚手架。
作用:可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。

5.mock server

这个目前还没有找到很合适的mock工具,包括rap也好,其他API文档工具也好,都做的不够完善,大多就是根据说明文件,例如swagger.json等生成一些死的静态的mock数据,不能够根据限定条件:例如“只能是数字,必传”等做出合理的回应。
简单来说就是支持的不够完善。

三、与SpringBoot整合

第一步、添加pom依赖
需要添加的依赖为swagger2核心包和swagger-ui(方便使用自带的ui界面)包
这里使用2.7.0版本为例

<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>

第二步、将swagger-ui中的界面配置至spring-boot配置文件中。

因为spring-boot有自己的一套web端拦截机制,若需要看到swagger发布的api文档界面,需要做一些特殊的配置,可以将springfox-swagger-ui包中的ui界面暴露给spring-boot资源环境。

@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

第三步、配置API文档页基本信息

spring-boot 和 swagger 整合时,使用注解注入相关配置。
通过这些配置可以指定在spring-boot启动时扫描哪些controller层的文件夹,
另外可以指定API文档页的标题和描述信息等内容。

@Configuration
@EnableSwagger2
public class Swagger2 {


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xx.web.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xx项目 RESTful APIs")
                .description("xx项目后台api接口文档")
                .version("1.0")
                .build();
    }

}

第四步、API文档编写示例

我们一般会在Controller层,将详尽的API接口输入输出在代码中通过注解进行相关描述,下面给出一个接口描写示例,具体的写法可以参考其api文档的具体说明:

@Api(value = "PageController", description = "用户登录登出接口")
@Controller
@RequestMapping("/")
public class PageController {

    @ApiOperation(value="用户登录", notes="用户登录接口")
    @ApiImplicitParams({
          @ApiImplicitParam(name = "username", value = "用户名", required = true ,dataType = "string"),
          @ApiImplicitParam(name = "passwd", value = "密码", required = true ,dataType = "string")
    })
    @RequestMapping(value = "/login",method = {RequestMethod.POST,RequestMethod.GET})
    @ResponseBody
    public ModelMap login(Users data, HttpServletRequest request){
       //ToDo
    }

}

第五步、通过ui界面,在线查看及测试API文档

访问localhost:8080/swagger-ui.html

ui

找到一个方法点进去

这里写图片描述
到这一步一个简单的demo也就完成

一个现成可以直接下载并运行的demo

git clone https://github.com/tianxuxu/de.git

四、如何将在线文档离线
整理一下生成离线文档的思路

首先给controller添加注解生成api
将路径”/v2/api-docs”下的文件生成.json文件
将.json文件生成中间文件.adoc文件
将.adoc文件合成自己想要的pdf文件或者html或者doc文件

这里其实我也不太明白
步骤大致就是额外需要的pom
添加文件格式转化所需swagger2markup和相关静态文件所需的包

<dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-mockmvc</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-staticdocs</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.github.robwin</groupId>
            <artifactId>assertj-swagger</artifactId>
            <version>0.2.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
            <version>1.2.0</version>
            <scope>test</scope>
        </dependency>

另外还需要在pom文件配置静态文件的生成目录啥的完整的pom参考后面附带的github项目这里的pom

我也不太明白为啥网上所有的例子都是都是通过运行mvn test生成文件的
只能附上test中的生成.json代码

@RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes = {SpringFoxSwagger2MarkupApplication.class, SwaggerConfig.class})
@AutoConfigureMockMvc
@WebAppConfiguration
public class Swagger2MarkupTests {

    private static final Logger LOG = LoggerFactory.getLogger(Swagger2MarkupTests.class);

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void createSpringFoxSwaggerJson() throws Exception {
        //String designFirstSwaggerLocation = Swagger2MarkupTest.class.getResource("/swagger.yaml").getPath();

        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir"); // mvn test
//        String outputDir = "D:\\workspace\\springfox-swagger2-demo\\target\\swagger"; // run as

        LOG.info("--------------------outputDir: {}--------------------", outputDir);
        MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
                .accept(MediaType.APPLICATION_JSON))
                                          .andExpect(status().isOk())
                                          .andReturn();

        MockHttpServletResponse response = mvcResult.getResponse();
        String swaggerJson = response.getContentAsString();
        Files.createDirectories(Paths.get(outputDir));
        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)){
            writer.write(swaggerJson);
        }
        LOG.info("--------------------swaggerJson create --------------------");
    }

}

因为整合SpringBoot熟悉了Swagger2的基本用法后那么再次查看Swagger2的实例就应该不再困难
这里附上一个swagger2的生成离线pdf/html的例子
这是别人写的一个例子,我忘记从哪找的了,但是我把它传到了github
这里可以下载

git clone https://github.com/tianxuxu/springfox_swagger2markup.git

导入项目完成后,执行mvn test
就可以看到它在pom中指定的目录完成静态文档的生成

这篇只能算是个入门的文章,可以快速了解下swagger2,对具体的api了解和使用还是要查看官方网站https://swagger.io/

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值