怎么使用Swagger2做API接口文档

在RESTFUL风格的影响下，前后端逐渐分的越来越开。

很早之前前端是由后端来渲染的，现在则不然，后端做后端的，前端根据RESTFUL会规定请求方法，请求信息，url路径，其中url路径就是很重要的一环。OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。目前V3.0版本的OpenAPI规范已经发布并开源

 

Swagger包含的工具集：

• Swagger编辑器： Swagger Editor允许您在浏览器中编辑YAML中的OpenAPI规范并实时预览文档。

• Swagger UI： Swagger UI是HTML，Javascript和CSS资产的集合，可以从符合OAS标准的API动态生成漂亮的文档。

• Swagger Codegen：允许根据OpenAPI规范自动生成API客户端库（SDK生成），服务器存根和文档。

• Swagger Parser：用于解析来自Java的OpenAPI定义的独立库

• Swagger Core：与Java相关的库，用于创建，使用和使用OpenAPI定义

• Swagger Inspector（免费）： API测试工具，可让您验证您的API并从现有API生成OpenAPI定义

• SwaggerHub（免费和商业）： API设计和文档，为使用OpenAPI的团队构建。

 

怎么让项目集成Swagger呢，第一步当然是引入依赖，Springboot集成了Swagger的依赖

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

 

然后编写一个配置类

@Configuration
@EnableSwagger2 // 加载引导类上或者配置类上都可以
public class SwaggerConfig {

    @Bean("商品平台")
    public Docket userApis() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("商品平台")
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) // 所有标了API注解的才在文档中展示
                .paths(PathSelectors.regex("/pms.*")) // pms下的所有请求
                .build()
                .apiInfo(apiInfo())
                .enable(true);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("商品平台接口文档")
                .description("提供商品平台的文档")
                .termsOfServiceUrl("https://blog.csdn.net/qq_34093082")
                .version("1.0")
                .build();
    }

}

 

前面是关于API的一些设置，后面是API文档的填写。

然后就是在具体的 地方应该加哪些注解的问题了。

/**
 @Api：修饰整个类，描述Controller的作用
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiParam：单个参数描述
 @ApiModel：用对象来接收参数
 @ApiProperty：用对象接收参数时，描述对象的一个字段
 @ApiResponse：HTTP响应其中1个描述
 @ApiResponses：HTTP响应整体描述
 @ApiIgnore：使用该注解忽略这个API
 @ApiError ：发生错误返回的信息
 @ApiImplicitParam：一个请求参数
 @ApiImplicitParams：多个请求参数
 */

 

你可以在controller里头这么写

 

 

这个反映到前端就是

 

再比如你也可以在实体类里头使用相关的注解

在前端显示的那就是