Swagger-ui配置

目录

文件夹结构

配置文件

import org.springframework.beans.factory.annotation.Value;
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 Swagger2Config {

    @Value("${swagger2.enable}")
    private boolean enable;

    @Bean
    public Docket baseApis() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("基础")
                .select()
                .apis(RequestHandlerSelectors.basePackage("*****.web.controller"))
                //指向为父级文件夹的同级controller文件夹，controller文件夹中所有添加了说明的都会再swagger中显示出来
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .enable(enable);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("项目接口目录")
                .description("可查看controller中的接口")
                .version("0.0.1")
                .build();
    }
}

查看路径

http://localhost:8080/swagger-ui.html#/
端口号：8080

基本接口展开：

/first接口：

文件说明

显示的列表中是controller文件夹中的java文件,内容是根据controller文件中的注释自动生成

controller文件

package  ****.web.controller;

import java.util.List;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import springfox.documentation.annotations.ApiIgnore;

@RequestMapping("/base")
@Api(tags = "基本接口")
@Controller
public class BaseController {
    public BaseController() {
    }

    @RequestMapping(value = "/ignore", produces = "application/json;charset=UTF-8", method = { RequestMethod.GET })
    @ResponseBody
    @ApiIgnore
    public String check() {
    }

    @RequestMapping(value = "/first", produces = "application/json;charset=UTF-8", method = { RequestMethod.GET })
    @ApiOperation("第一个接口说明")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "cardId", value = "card Id", required = true, dataType = "long", paramType = "path")
    })
    public User getUser(@PathVariable Long cardId){
      
    }

    @RequestMapping(value = "/second", produces = "application/json;charset=UTF-8", method = { RequestMethod.GET })
    @ApiOperation("第二个接口说明")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "input name", required = true, dataType = "string", paramType = "header")
    })
    @ResponseBody
    public List<User>  getUserList(@PathVariable String name) {
     
    }

    @RequestMapping(value = "/third", produces = "application/json;charset=UTF-8", method = { RequestMethod.GET })
    @ApiOperation("第三个接口说明")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "cardId", value = "cardId", required = true, dataType = "long", paramType = "path")
    })
    @ResponseBody
    public List<User> getCustomer(@PathVariable Long idPerson) {
        return list;
    }

    @RequestMapping(value = "/fourth", produces = "application/json;charset=UTF-8", method = { RequestMethod.GET })
    @ApiOperation("第四个接口说明")
    @ResponseBody
    public void getFourth() {
    }

}

controller文件中的注释

Class类注释

@RequestMapping("/baseUrl")

设置java文件的请求访问前缀

@Api(tags = “基本接口”)

设置java文件的展示的名称

@Controller

表示java文件是controller文件

Class内容注释

@ApiIgnore

不展示的接口

@RequestMapping

请求路径

@ApiOperation

请求接口的说明

@ResponseBody

相应请求内容

@ApiImplicitParams

    @ApiImplicitParams({
            @ApiImplicitParam(name = "cardId", 
            value = "card Id", required = true, dataType = "long", paramType = "path")
    })

• @ApiImplicitParams 请求需要的参数列表
• @ApiImplicitParam其中一个参数的设置
• name：参数名称
• value ：参数值
• required ：是否必填
• dataType ：参数类型
• paramType ：是属于路径上的参数，还是请求header中的参数

@PathVariable

变量，即使不存在于@ApiImplicitParams中会显示出来