springmvc整合 swagger

最新推荐文章于 2025-06-19 14:49:32 发布

原创最新推荐文章于 2025-06-19 14:49:32 发布 · 191 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#swagger #springmvc

swagger 专栏收录该内容

2 篇文章

订阅专栏

本文介绍如何使用Swagger为Spring Boot项目创建API文档。包括Swagger的依赖引入、配置类编写、控制器注解使用等内容。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

在线Demo: http://petstore.swagger.io
Swagger官网：http://swagger.io
GitHub地址：https://github.com/swagger-api
官方注解文档：http://docs.swagger.io/swagger-core/apidocs/index.html
Swagger-UI地址：https://github.com/swagger-api/swagger-ui
千峰视屏：
https://tv.sohu.com/v/dXMvMjQwNzYwNzQ4LzEwMDcyODMxMy5zaHRtbA==.html

1.依赖：

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

注：之前使用2.7.0 发现@Api不好使

2.配置类

//启用Swagger2
@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurationSupport {

    @Bean
    public Docket creatApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() //选择哪些路径和api会生成document
                .apis(RequestHandlerSelectors.basePackage("com.ohaotian.authority.controller"))//controller路径
                .apis(RequestHandlerSelectors.any())   //对所有api进行监控
                .paths(PathSelectors.any())  //对所有路径进行监控
                .build();
    }

    //接口文档的一些基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("权限中心")  //文档主标题
                .description("权限中心接口文档")    //文档描述
                .version("1.0.0")       //API的版本
                .termsOfServiceUrl("###")
                .license("LICENSE")
                .licenseUrl("###")
                .contact("tydic")  // 联系人
                .build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");

    }

注意：修改controller路径
3.spring-mvc.xml

    <!--swagger-->
    <!-- 注解方式：自动扫描该包 -->
    <context:component-scan base-package="com.oahotian.authority.config" />
    <bean class="com.oahotian.authority.config.Swagger2Config" id="swagger2Config"/>
    <!--过滤掉swagger-ui的静态资源文件-->
    <mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
    <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

4.Controller

头部：

@Api(description="子系统管理",tags="子系统管理接口")
@Controller
@RequestMapping(value = "/application", method = {RequestMethod.GET, RequestMethod.POST})
public class ApplicationController {

接口：


    //ApiOperation()用于方法，表示一个http请求的操作
    @ApiOperation(httpMethod="GET",value="接口标题:查询有效子系统",notes="接口的notes说明：需要xxx")
    // 用于方法,表示单独的请求参数
    @ApiImplicitParams({
            @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
            @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
    @RequestMapping("/select")
    @BusiResponseBody
    public Object selectValidApplication() {

5.访问：
swagger界面
http://localhost:8081/swagger-ui.html#/
接口的json格式：
http://localhost:8081/v2/api-docs

注：
出现Unable to infer base url.
This is common when using dynamic servlet registration or when the API is behind an API Gateway.
The base url is the root of where all the swagger resources are served. For e.g. if the api is available at
http://example.org/api/v2/api-docs then the base url is http://example.org/api/.
Please enter the location manually:

发现web.xml中

    <servlet-mapping>
        <servlet-name>mvc-dispatcher</servlet-name>
        <url-pattern>/rest/authority/*</url-pattern>
    </servlet-mapping>

重新访问：http://localhost:8081/rest/authority/swagger-ui.html#/ ok!
在这里插入图片描述

7.swagger界面介绍：
在这里插入图片描述
7.1底下的Models是返回的模型

8.注解说明

8.1
	表示标识这个类是swagger的资源  controller在swagger上显示的名字
	@Api(description="子系统管理",tags="子系统管理接口")

8.2
	ApiOperation()用于方法，表示一个http请求的操作
	@ApiOperation(httpMethod="GET",value="接口标题:查询有效子系统",notes="接口的notes说明：
	需要xxx")注：如果httpMethod不设置，swagger会出现post和get两种请求

8.3
	用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）
	@ApiParam(name="saveApplicationReqBO",value="新增saveApplicationReqBO",required=true)

8.4
	@ApiIgnore()用于类，方法，方法参数，表示这个方法或者类被忽略 

8.5
	@ApiModel()用于类，表示对类进行说明，用于参数用实体类接收 
    @ApiModelProperty()用于方法，字段 ，表示对model属性的说明或者数据操作更改

8.6
	@ApiImplicitParam() 用于方法，表示单独的请求参数
	@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

    @ApiImplicitParams({
        @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
        @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})