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/", "bestlmc@foxmail.com"))
                .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("bestlmc@foxmail.com")
                .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("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也一同打包部署到服务器上面，springfox会出现错误，无法正常访问swagger-ui。但是使用Knife4j的话，则不会出现这个问题。具体的原因有可能是因为swagger默认生成的地址是localhost，而云服务器的地址不一致而导致。参考：https://blog.csdn.net/q944324153/article/details/77833723