SpringBoot集成Swagger构建api文档的操作
都让你们叫老了 人气:0最近在做项目的时候,一直用一个叫做API的东西,controller注解我会写,这个东西我也会用,但是我确实不知道这个东西是个什么,有点神奇。关键还坑了我一次,他的注解会影响到代码的运行,不光是起到注解的作用。所以我就研究了一下。
Swagger是什么:THE WORLD'S MOST POPULAR API TOOLING
根据官网的介绍:
Swagger Inspector:测试API和生成OpenAPI的开发工具。Swagger Inspector的建立是为了解决开发者的三个主要目标。
1、执行简单的API测试
2、生成OpenAPI文档
3、探索新的API功能
我的理解Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案。根据我的使用,当然我只是最简单的使用,我感觉Swagger有以下几个优点:
1、Swagger可以整合到代码中,在开发时通过注解,编写注释,自动生成API文档。
2、将前端后台分开,不会有过分的依赖。
3、界面清晰,无论是editor的实时展示还是ui的展示都十分人性化,如果自己仅仅用markdown来编写,又要纠结该如何展现,十分痛苦。
下面的两点我还没有进行实践:
1、支持Json和yaml来编写API文档,并且支持导出为json、yaml、markdown等格式
2、如果编写好了API了,可以自动生成相应的SDK,没错,可能你的API接口代码还没有开始写,它就能帮你制作相应的SDK了,而且支持几乎所有主流编程语言的SDK。
SpringBoot,Maven构建SwaggerAPI文档
第一步:创建SpringBoot Web项目
在这里就不过多进行介绍,只是说一下可能出现的问题:创建好项目之后目录结构不对,只有src/main/resources文件夹。下图所示
这时候只需要将JDK版本升级到你安装的版本就可以,其他文件夹就可以显现出来:
第二步:创建类以及配置pom.xml
1:配置pom.xml,添加依赖包:
第一个是API获取的包,第二是官方给出的一个ui界面。三和四是spring boot 需要的jar包。
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency>
2:配置Swagger,创建SwaggerConfig.java类
@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com")) .paths(PathSelectors.any()).build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2构建RESTful APIs") .description("myapp") .termsOfServiceUrl("http://blog.csdn.net/java_yes") .version("1.0").build(); } }
这里有个特别需要注意的地方:
RequestHandlerSelectors.basePackage(“com.swagger”),这是扫描注解的配置,即你的API接口位置。文章最后我会做总结。
3:创建SpringBoot启动类
@SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }
4:创建controller
在这里我创建两个controller,为了解释@RequestMapping();这两个Controller没有任何实际意义,可以随意创建,我只是为了测试SwaggerAPI
GreetingController
@RestController @RequestMapping(value = "/test") public class GreetingController { private static final String template = "Hello, %s!"; private final AtomicLong counter = new AtomicLong(); @RequestMapping(value = "/swagger") //@RequestMapping("/swagger") //@RequestMapping(value = "/swagger",method = RequestMethod.POST) public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) { return new Greeting(counter.incrementAndGet(), String.format(template, name)); } }
BookController
@RestController @Api(tags = "BookController", description = "BookController | 通过书来测试swagger") @RequestMapping(value = "/books") public class BookController { Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>()); @ApiOperation(value="创建图书", notes="创建图书") @ApiImplicitParam(name = "book", value = "图书详细实体", required = true, dataType = "Book") @RequestMapping(value="", method=RequestMethod.POST) public String postBook(@RequestBody Book book) { books.put(book.getId(), book); return "success"; } @ApiOperation(value = "获图书细信息", notes = "根据url的id来获取详细信息") @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long", paramType = "path") @RequestMapping(value = "/{id}", method = RequestMethod.GET) public Book getBook(@PathVariable Long id) { return books.get(id); } }
5:创建SpringBoot 启动类:
@SpringBootApplication @ComponentScan(basePackages={"com"}) public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }
第三步:启动Swagger
OK,到此为止,整个Swagger我们已经配置完毕。此时访问http://localhost:8080/swagger-ui.html#/greeting-controller。就可以看到Swagger-UI了。如下图所示
同样,根据@RequestMapping()的路径我们可以进行访问,再API中进行测试一样。这里我就进行演示。
坑!!!!我在配置过程中出现的错误;
我先发一下我的文件结构:
1:什么都配置了,但是API什么都不显示。如图所示:
这个就是我上面说到的问题:RequestHandlerSelectors.basePackage(“com.swagger”)
这个地方配置的是你swagger要加载的接口所在的包名。会去扫秒这个包下的所有Controller。大家看我的文件结构。
如果你配置的是RequestHandlerSelectors.basePackage(“com”),那么就会扫描所有com包下的Controller,包括com.swagger;以及com.controller。效果就是这样:
如果你只是单独配置RequestHandlerSelectors.basePackage(“com.swagger”),或者RequestHandlerSelectors.basePackage(“com.swagger”)。那么就会显示一个。
2:我配置的是RequestHandlerSelectors.basePackage(“com”),但API还是只显示一个,而且不显示Controller直接访问地址也报错,如图所示:
这个时候可能是SpringBoot的问题了。他并没有加载到你的另一个controller。
SpringBoot启动类和Controller类需要在同一包下,controller要在父类包下。
这个时候有两种解决方案:
1、将未加载的Conrtoller类移动到SpringBoot启动类所在包。或者将其包名改为启动类的子包。
2、如上述代码,在启动类上加注释:@ComponentScan(basePackages={“com”})。该注释会扫描所有com包下的controller并加载。
为什么我GreetingController没有写rest方法。但是API中显示了所有呢?
这个要用@RequestMapping();进行解释了。
1、@RequestMapping(value = “/swagger”)或者@RequestMapping(“/swagger”)这么写的时候,就会加载所有method。
2、@RequestMapping(value = “/swagger”,method = RequestMethod.POST),当你自己设置mathod的时候,就会只创建你设置的method。
以上这篇SpringBoot集成Swagger构建api文档的操作就是小编分享给大家的全部内容了,希望能给大家一个参考,也希望大家多多支持。
加载全部内容