Springboot整合Swagger

1.添加依赖

        <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>

说明：笔者最初使用2.20.5版本，出现下述两个异常，遂改为2.9.2版本。

• 接口页面无法访问：Unable to infer base url.
• 注解@EnableSwagger2找不到。

 2.添加配置

/**
 * Swagger配置：开启Swagger,并托管至容器
 *
 * @author Li Bin
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 可以用来指定上下文基础URL
                .pathMapping("/userservice/")
                .select()
                // 添加了Api注解的类并且添加了ApiOperation注解的方法生成接口
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 生成接口的包
                .apis(RequestHandlerSelectors.basePackage("com.springboot.learn.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    /**
     * 接口基本信息
     */
    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot 整合 Swagger")
                .description("SpringBoot 整合 Swagger")
                .version("1.0")
                .contact(new Contact("xxx", "www.boot.learn", "xxx@163.com"))
                .build();
    }
}

3.添加API注解

@Api(tags = "用户管理")
@RestController
@RequestMapping(value = "/user", produces = MediaType.APPLICATION_JSON_VALUE)
public class UserController {
    @Autowired
    private IUserService userService;

    @ApiOperation("删除用户")
    @PostMapping("delete/{userName}")
    @ApiImplicitParam(name = "userName", value = "用户名称", dataType = "String", required = true)
    public ResultBean<Boolean> delete(@PathVariable("userName") String userName) {
        System.out.println("delete   >>>>    " + userName);
        LambdaQueryWrapper<User> queryWrapper = new LambdaQueryWrapper<>();
        queryWrapper.eq(User::getUserName, userName);
        return ResultBean.success(userService.remove(queryWrapper));
    }
}

4.接口访问地址

http://localhost:8080/swagger-ui.html

5.常见注解

注解@Api用于指定整个类的接口信息

@Api(tags = "用户管理")

注解@ApiOperation用于指定具体方法的接口信息
 
@ApiOperation("删除用户")

注解@ApiModel用于指定对象入参的信息

@ApiModel("用户信息")

注解@ApiModelProperty用于描述对象入参中的字段

@ApiModelProperty("用户名")

produces 用于指定返回数据类型，可用于方法，亦可用于类。

@RequestMapping(value = "/user", produces = MediaType.APPLICATION_JSON_VALUE)

注解@ApiImplicitParam用于指定参数，多个可用@ApiImplicitParam。

@ApiImplicitParam(name = "userName", value = "用户名称", dataType = "String", required = true)