Swagger2快速使用

OpenAPI规范的API开发工具框架

常用注解

// @Api: 修饰整个类，描述Controller的作用
@Api(value = "注册登陆", tags = "注册登陆相关接口")
// @ApiOperation: 描述一个类的一个方法，或者说一个接口
@ApiOperation(value = "用户注册", notes = "用户注册", httpMethod = "POST")
@ApiParam			// 单个参数描述
// @ApiModel: 用对象来接收参数
@ApiModel(value = "用户对象BO", description = "用户从客户端传入的数据的封装")
// @ApiModelProperty: 用对象接收参数时，描述对象的一个字段
@ApiModelProperty(value = "用户名", name = "username", example = "Orcas", required = true)
@ApiResponse        // HTTP响应其中1个描述
@ApiResponses       // HTTP响应整体描述
@ApiIgnore		    // 使用该注解忽略这个API 
@ApiError 		    // 发生错误返回的信息
@ApiImplicitParam   // 一个请求参数
@ApiImplicitParams  // 多个请求参数
   =》 @ApiImplicitParams({
            @ApiImplicitParam(name = "page", value = "页码", required = true, paramType = "path", dataType = "int"),
            @ApiImplicitParam(name = "size", value = "每页记录数", required = true, paramType = "path", dataType = "int")})

@ApiImplicitParam属性

配置文件

依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

@Configuration
@EnableSwagger2
public class Swagger2Configuration {
    
    /**
     * Swagger2 核心配置 docket
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // 指定API类型
                .apiInfo(apiInfo())                     // 定义API文档汇总信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.orcas.controller"))  // 指定 controller 包
                .paths(PathSelectors.any())             // 选择包下所有的 controller
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试接口api文档")
                .description("关于测试接口api文档")
                .contact(new Contact("Orcas",
                        "https://blog.csdn.net/u012211603",
                        "test@163.com"))                         // 联系人信息
                .termsOfServiceUrl("https://blog.csdn.net/u012211603") // 网站地址
                .version("1.0.0")                                      // 版本号
                .build();
    }
}

访问地址

http://localhost:[port]/swagger-ui/index.html

404

3.0.0 版本
注意下访问路径是否少了 /index.html，和以前版本不同。

查看SwaggerUiWebMvcConfigurer类中的访问路径。

换肤

官方UI

引入其他偏好的界面依赖，访问相应的地址

http://localhost:[port]/doc.html

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

显示优化

通过使用常用注解
@Api / @ApiOperation / @ ApiIgnore / @ApiModel / @ApiModelProperty等来完善文档。

或