SpringBoot整合Swagger2

Posted 2020-11-24 魔有追求

SpringBoot整合Swagger2

引入依赖

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

配置类

package com.xuecheng.api.config;

import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

//
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
    /*
    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:
    原因：主启动没有扫描到Swagger2Configuration配置类，添加@ComponentScan(basePackages = "com.xuecheng.api")
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //.apiInfo(apiInfo())
                .apiInfo(
                        new ApiInfoBuilder()
                            .title("SpringBoot整合Swagger")
                            .description("SpringBoot整合Swagger详细信息。。。")
                            .license("ApacheL2.0")
                            .licenseUrl("http://www.baidu.com")
                            .version("1.0.0")
                            .build()
                )
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xuecheng"))
                //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("学成网api文档")
                .description("学成网api文档")
                //.termsOfServiceUrl("/")
                .version("1.0.0")
                .build();
    }
}

package com.xuecheng.api.cms;

import com.xuecheng.framework.domain.cms.request.QueryPageRequest;
import com.xuecheng.framework.model.response.QueryResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@Api(tags = "cms页面管理接口")
public interface CmsPageControllerApi {
    @ApiOperation("分页查询")
    @ApiImplicitParams({
            @ApiImplicitParam("当前页"),
            @ApiImplicitParam("页大小")
    })
    QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest);
}

package com.xuecheng.manage_cms.web.controller;

import com.xuecheng.api.cms.CmsPageControllerApi;
import com.xuecheng.framework.domain.cms.CmsPage;
import com.xuecheng.framework.domain.cms.request.QueryPageRequest;
import com.xuecheng.framework.model.response.CommonCode;
import com.xuecheng.framework.model.response.QueryResponseResult;
import com.xuecheng.framework.model.response.QueryResult;
import com.xuecheng.manage_cms.service.CmsPageService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@RestController
@Slf4j
public class CmsPageController implements CmsPageControllerApi {
    @Autowired
    private CmsPageService cmsPageService;

    //这个没有加@ApiOperation注解的接口也出现在了文档中
    @RequestMapping("/demo")
    public String demo(String name){
        return name;
    }

    @GetMapping("/list/{page}/{size}")
    @Override
    public QueryResponseResult findList(@PathVariable("page") int page, @PathVariable("size")int size, QueryPageRequest queryPageRequest) {
        log.info("查询Cms分页");
        QueryResult<CmsPage> queryResult = new QueryResult<>();
        queryResult.setTotal(2);
        List<CmsPage> cmsPageList = new ArrayList<>();
        CmsPage cmsPage = new CmsPage();
        cmsPage.setPageName("页面1");
        cmsPageList.add(cmsPage);
        queryResult.setList(cmsPageList);
        QueryResponseResult result = new QueryResponseResult(CommonCode.SUCCESS, queryResult);

        //QueryResponseResult result = cmsPageService.findList(page, size, queryPageRequest);
        return result;
    }
}

主启动类

package com.xuecheng.manage_cms;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan(basePackages = "com.xuecheng.api")
//发现如果手动指定了@ComponentScan就不会扫描当前项目的了，所以下面要加上扫描当前项目
@ComponentScan(basePackages = "com.xuecheng.manage_cms")
public class ManageCmsApplication {
    public static void main(String[] args) {
        SpringApplication.run(ManageCmsApplication.class, args);
    }
}

bugs

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:
原因:主启动和swagger配置是分开到2个模块的，主启动没有扫描到Swagger2Configuration配置类，添加@ComponentScan(basePackages = "com.xuecheng.api")

可以访问swagger在线文档描述信息，但是不出现文档接口。
原因：主启动类上主动加上了@ComponentScan(basePackages = "com.xuecheng.api")，扫描指定的包后，就没有像之前自动扫描当前项目下的包，需要手动加上扫描当前项目的包。@ComponentScan(basePackages = "com.xuecheng.manage_cms")