Swagger的使用和部署

简介

Swagger是什么?

官方解释:Swagger是一组围绕 OpenAPI 规范构建的开源工具,可帮助您设计、构建、记录和使用 REST API。

Swagger的使用和部署

https://swagger.io/docs/specification/about/

个人理解:Swagger就是将你的接口生成可视化的html供你查看、调用、测试的一个工具。现在来说挺方便开发的,特别是前后端分离的项目。

 

Swagger的版本和UI

截至今日,Swagger已经更新到3.0的版本了。参考官网:https://swagger.io/

要在spring框架的项目使用swagger,一般是用到以下两个项目代替

SpringFox

官网:http://springfox.github.io/springfox/docs/current/

一般用这个多一点。

SpringDoc

官网:https://springdoc.org/

spring框架的社区项目,能适配spring-boot框架。

 

UI

Swagger-ui

swagger原生的ui相对简单

使用springfox

maven

 <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-boot-starter</artifactId>
          <version>3.0.0</version>
      </dependency>

main.class

@SpringBootApplication
@EnableOpenApi
@ComponentScan(basePackages = {
       "com.bestlmc.xxx.config""})
public class AdminApplication {
   public static void main(String[] args) {
       SpringApplication.run(AdminApplication.class,args);
  }
}

Configuration

@Configuration
public class Swagger3Config {
   @Bean
   public Docket createRestApi() {
       return new Docket(DocumentationType.OAS_30)
              .apiInfo(apiInfo())
              .select()
              .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
              .paths(PathSelectors.any())
              .build();
  }

   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
              .title("狸花猫接口文档")
              .description("更多请咨询服务开发者Bestlmc")
              .contact(new Contact("bestlmc", "http://www.bestlmc.xyz/", "bestlmc@foxmail.com"))
              .version("1.0")
              .build();
  }
}

效果图:

Swagger的使用和部署

swagger-bootstrap-ui

如果你不喜欢swagger-ui的话,可以尝试以下swagger-bootstrap-ui。这样看起来会更简洁一点:

maven:

<dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-swagger2</artifactId>
          <version>2.9.2</version>
      </dependency>
      <dependency>
          <groupId>com.github.xiaoymin</groupId>
          <artifactId>swagger-bootstrap-ui</artifactId>
          <version>1.9.6</version>
      </dependency>

Configuration

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfiguration {
   @Bean
   public Docket createRestApi() {
       return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.bestlmc.lihuamao.admin.controller"))
              .paths(PathSelectors.any())
              .build();
  }
   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
              .title("狸花猫接口文档")
              .description("swagger-bootstrap-ui")
              .termsOfServiceUrl("http://localhost:8001/")
              .contact("bestlmc@foxmail.com")
              .version("1.0")
              .build();
  }
}

效果图:

Swagger的使用和部署

Knife4j

Knife4j作为swagger-bootstrap-ui的升级版,拥有更好看的ui。也变得更方便

官网参考:https://doc.xiaominfo.com/knife4j/

maven

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-boot-starter</artifactId>
  <version>2.0.7</version>
</dependency>

Configuration

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

   @Bean(value = "defaultApi2")
   public Docket defaultApi2() {
       Docket docket=new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(new ApiInfoBuilder()
                       //.title("swagger-bootstrap-ui-demo RESTful APIs")
                      .description("# swagger-bootstrap-ui-demo RESTful APIs")
                      .termsOfServiceUrl("http://www.xx.com/")
                      .contact("xx@qq.com")
                      .version("1.0")
                      .build())
               //分组名称
              .groupName("2.X版本")
              .select()
               //这里指定Controller扫描包路径
              .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
              .paths(PathSelectors.any())
              .build();
       return docket;
  }
}

效果图:

Swagger的使用和部署

 

部署

如果要将swagger也一同打包部署到服务器上面,springfox会出现错误,无法正常访问swagger-ui。但是使用Knife4j的话,则不会出现这个问题。具体的原因有可能是因为swagger默认生成的地址是localhost,而云服务器的地址不一致而导致。参考:https://blog.csdn.net/q944324153/article/details/77833723

上一篇:全新Swagger3.0教程,OAS3快速配置指南,实现API接口文档自动化!


下一篇:spring boot 整合 swagger