0%

Springboot集成Swagger2

发表于 分类于
Swagger是一个功能强大且易于使用的API开发人员工具套件，适用于团队和个人，支持从整个API生命周期（从设计和文档到测试和部署）的开发。

Springboot集成Swagger2

一、介绍：

Swagger是一个功能强大且易于使用的API开发人员工具套件，适用于团队和个人，支持从整个API生命周期（从设计和文档到测试和部署）的开发。
Swagger由开源，免费和商用工具组成，允许任何人，从技术工程师到街头智能产品经理，构建每个人都喜欢的令人惊叹的API。
Swagger最初是作为2010年设计RESTful API的简单开源规范而开发的。开源工具如Swagger UI，Swagger Editor和Swagger Codegen也被开发用于更好地实现和可视化规范中定义的API。Swagger项目由规范和开源工具组成，非常受欢迎，创建了一个由社区驱动的工具组成的庞大生态系统。
2015年，Swagger项目被SmartBear Software收购。Swagger规范被捐赠给Linux基金会并重命名为OpenAPI规范以正式标准化REST API的描述方式。建立OpenAPI倡议是为了以公开和透明的方式指导美洲国家组织的发展。
从那以后，Swagger成为最受欢迎的工具套件，可以在API生命周期中充分利用OAS的强大功能。

二、Springboot添加Swagger2依赖

1
2
3
4
5
6
7
8
9
10
11
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

三、添加Swagger2配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.Collections;

@Configuration
@EnableSwagger2
public class SpringFoxConfig {
    @Bean
    public Docket apiDocket(){
        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors
                .basePackage("你的controller包，如com.example.controller")).paths(PathSelectors.any())
                .build().apiInfo(getApiInfo());
    }

    private ApiInfo getApiInfo(){
        return new ApiInfo(
                "TITLE",
                "DESCIPRION",
                "VERSION",
                "TEAMS OF SERVICE URL",
                new Contact("NAME","URL","EMAIL"),
                "LICENSE",
                "LICENSE URL",
                Collections.emptyList()
        );
    }
}
WebConfig用于访问静态资源
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import org.springframework.context.annotation.Configuration;
import org.springframework.http.CacheControl;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import java.util.concurrent.TimeUnit;
nfiguration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/")
                .setCacheControl(CacheControl.maxAge(1, TimeUnit.HOURS).cachePublic());
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/")
                .setCacheControl(CacheControl.maxAge(1, TimeUnit.HOURS).cachePublic());
    }

}

四、添加注解

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.util.MultiValueMap;
import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpServletRequest;

@RestController
public class ForumController {
    /**
     * by zhangjia
     * 获取板块分页后页数
     */
    @ApiOperation(value = "获取板块分页后页数",notes = "板块页数")
    @RequestMapping(value = "/pnum/{fid}/{isDigest}", produces = "application/json;charset=UTF-8")
    public Response pageNum(@CookieValue(defaultValue = "0") int uid,
                            @CookieValue(defaultValue = "") String sid,
                            @ApiParam @PathVariable int fid,
                            @ApiParam @PathVariable int isDigest,
                            @Autowired HttpServletRequest request) {
        return forumService.getPageNum(fid, isDigest);
    }
通过访问：http://localhost:8080/v2/api-docs ，能测试生成的api是否可用。此时返回的是一个json形式的页面，可读性不好。可以通过Swagger UI来生成一个可读性良好的api页面。
访问：http://localhost:8080/your-app-root/swagger-ui.html 就可以看到可读性较好的api文档页面。

这里写图片描述

五、常见注解介绍

Swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

参考文章：
https://blog.csdn.net/fansunion/article/details/51923720
https://blog.csdn.net/saytime/article/details/74937664
https://blog.csdn.net/Phone_1070333541/article/details/80949040