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

最新推荐文章于 2022-10-19 14:37:33 发布

菜鸡旭旭

最新推荐文章于 2022-10-19 14:37:33 发布

阅读量1.0k

点赞数

分类专栏： swagger2 文章标签： swagger2 SpringBoot

本文链接：https://blog.csdn.net/fengyuhan123/article/details/80280050

版权

swagger2 专栏收录该内容

2 篇文章 0 订阅

订阅专栏

一、理论基础

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

找到一个方法点进去

这里写图片描述
到这一步一个简单的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/。

菜鸡旭旭

关注

0
点赞
踩
2

收藏

觉得还不错? 一键收藏
0
评论
复制链接

分享到 QQ

分享到新浪微博

扫一扫

专栏目录