相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档。
手写Api文档的几个痛点:
- 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时。
- 接口返回结果不明确
- 不能直接在线测试接口,通常需要使用工具,比如postman
- 接口文档太多,不好管理
Swagger也就是为了解决这个问题,当然也不能说Swagger就一定是完美的,当然也有缺点,最明显的就是代码移入性比较强。
其他的不多说,想要了解Swagger的,可以去Swagger官网,可以直接使用Swagger editor编写接口文档,当然我们这里讲解的是SpringBoot整合Swagger2,直接生成接口文档的方式。
一、添加依赖
- <!-- Swagger相关依赖包 -->
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger2</artifactId>
- <version>2.2.2</version>
- </dependency>
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger-ui</artifactId>
- <version>2.2.2</version>
- </dependency>
二、Swagger配置类
- import java.util.Collections;
- import org.springframework.context.annotation.Bean;
- import org.springframework.context.annotation.Configuration;
- import springfox.documentation.builders.ApiInfoBuilder;
- import springfox.documentation.builders.ParameterBuilder;
- import springfox.documentation.builders.PathSelectors;
- import springfox.documentation.builders.RequestHandlerSelectors;
- import springfox.documentation.schema.ModelRef;
- 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 Swagger2 {
- @Bean
- public Docket createRestApi() {
- return new Docket(DocumentationType.SWAGGER_2)
- .apiInfo(apiInfo())
- .select()
- .apis(RequestHandlerSelectors.basePackage("包名称"))
- .paths(PathSelectors.any())
- .build()
- .globalOperationParameters(
- Collections.singletonList(new ParameterBuilder()
- .name("token")
- .description("token")
- .modelRef(new ModelRef("string"))
- .parameterType("header")
- .required(false)
- .build())
- );
- }
- private ApiInfo apiInfo() {
- return new ApiInfoBuilder()
- .title("标题名称")
- .description("描述")
- .termsOfServiceUrl("服务网址")
- .contact("作者")
- .version("版本")
- .build();
- }
- }
注:用@Configuration注解该类,等价于XML中配置beans;用@Bean标注方法等价于XML中配置bean。
@EnableSwagger2表示开启Swagger