Swagger的使用和部署

簡介

Swagger是什么？

官方解釋：Swagger是一組圍繞 OpenAPI 規范構建的開源工具，可幫助您設計、構建、記錄和使用 REST API。

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/", "[e-mail]"))
               .version("1.0")
               .build();
   }
}
​

效果圖：

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("[e-mail]")
               .version("1.0")
               .build();
   }
}

效果圖：

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("[e-mail]")
                       .version("1.0")
                       .build())
                //分組名稱
               .groupName("2.X版本")
               .select()
                //這里指定Controller掃描包路徑
               .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
               .paths(PathSelectors.any())
               .build();
        return docket;
   }
}

效果圖：

 

部署

如果要將swagger也一同打包部署到服務器上面，springfox會出現錯誤，無法正常訪問swagger-ui。但是使用Knife4j的話，則不會出現這個問題。具體的原因有可能是因為swagger默認生成的地址是localhost，而雲服務器的地址不一致而導致。參考：https://blog.csdn.net/q944324153/article/details/77833723