Swagger

1.什么是Swagger

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。

Swagger是符合OpenAPI规范的接口开发工具，支持从设计和文档到测试和部署的整个API生命周 期的开发。 (https://swagger.io/)

2.Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用 

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述 

@ApiModel：用对象来接收参数 

@ApiModelProperty：用对象接收参数时，描述对象的一个字段 

@ApiResponse：HTTP响应其中1个描述 

@ApiResponses：HTTP响应整体描述 

@ApiIgnore：使用该注解忽略这个API 

@ApiError ：发生错误返回的信息 

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数

3.Swagger生成接口文档的工作原理

1、系统启动，扫描到api工程中的Swagger2Confifiguration类

2、在此类中指定了包路径com.xuecheng，找到在此包下及子包下标记有@RestController注解的controller类

3、根据controller类中的Swagger注解生成接口文档。

4.Swagger应用举例

1)先定义一个配置类

@Configuration
@EnableSwagger2
public class Swagger2Configuration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xuecheng"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("朱大帅网api文档")
                .description("朱大帅网api文档")
//                .termsOfServiceUrl("/")
                .version("1.0")
                .build();
    }

}

2)修改接口工程中页面查询接口，添加Swagger注解

@RestController
@RequestMapping("/cms/page")
@Api(value="cms页面管理接口",description = "cms页面管理接口，提供页面的增、删、改、查")
public class CmsPageController implements CmsPageControllerApi {

    @Autowired
    PageService pageService;

    @Override
    @GetMapping("/list/{page}/{size}")
    @ApiOperation("分页查询页面列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name="page",value = "页 码",required=true,paramType="path",dataType="int"),
            @ApiImplicitParam(name="size",value = "每页记录 数",required=true,paramType="path",dataType="int")
    })
    public QueryResponseResult findList(@PathVariable("page") int page, @PathVariable("size")int size, QueryPageRequest queryPageRequest) {
        return pageService.findList(page,size,queryPageRequest);
    }
}

3)实体类中使用注解 ApiModelProperty 对属性注释

@Data
public class QueryPageRequest extends RequestData {
    //站点id
    @ApiModelProperty("站点id")
    private String siteId;
    //页面ID
    @ApiModelProperty("页面ID")
    private String pageId;
    //页面名称
    private String pageName;
    //别名
    private String pageAliase;
    //模版id
    private String templateId;
}

4)测试

访问路径:http://localhost:31001/swagger-ui.html(你本地项目的访问路径加swagger后缀)

结果: