swagger2 的简单应用

swagger简述

它允许您使用JSON或YAML元数据描述API的属性。它还提供了一个Web UI，它可以将元数据转换为一个很好的HTML文档。此外，通过该UI，您不仅可以浏览有关API端点的信息，还可以将UI用作REST客户端 - 你可以调用任何端点，指定要发送的数据并检查响应。

然而，手动编写此类文档并在代码更改时保持更新是不现实的。这就是SpringFox发挥作用的地方。它是Spring Framework的Swagger集成。它可以自动检查你的类，检测控制器，它们的方法，它们使用的模型类以及它们映射到的URL。没有任何手写文档，只需检查应用程序中的类，它就可以生成大量有关API的信息。

作用：

1. 接口的文档在线自动生成。
2. 功能测试。

使用：

依赖：

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

创建Swagger2配置类：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	/**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * 
     * @return
     */
    private List<Parameter> parameters = new ArrayList<>();

    @Bean
    public Docket createRestApi() {

        final String basePackage = "cn.xxx.ict.controller";

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .globalOperationParameters(parameters)
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }
	/**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("ict")
                .description("ictapi文档")
                .termsOfServiceUrl("hostname")
                .contact(new Contact("XXX", "xxxurl", "XXX"))
                .version("1.0")
                .build();
    }
}

Controller注解实例

@RestController
@RequestMapping("/compare")
@Api(tags = "2", description = "对比历史")
public class CompareController {
    @Autowired
    private ProjectService projectService;
    @Autowired
    private RegularService regularService;
    @Autowired
    private CompareService compareService;

    @ApiOperation(value = "对比列表", notes = "对比列表")
    @RequestMapping(value = "/list", method = RequestMethod.GET)
    public Result<List<CompareVo>> list() {
        List<CompareVo> compareVoList = new Vector<>();
        List<Project> projectList = projectService.list(new QueryWrapper<>());
        projectList.stream().forEach(project -> {
            List<Compare> compareList = compareService.list(new QueryWrapper<Compare>().select().eq("project_id", project.getProjectId()));
            ......
        });

        return Result.success(compareVoList);
    }
}

swagger 注解具体解释

作用范围	API	使用位置
对象属性	@ApiModelProperty	用在参数对象的字段上
协议集描述	@Api	用在Conntroller类上
协议描述	@ApiOperation	用在controller方法上
Response集	@ApiResponses	用在controller方法上
Response	@ApiResponse	用在@ApiResponses里面
非对象参数集	@ApilmplicitParams	用在controller方法上
描述返回对象的意义	@ApiModel	用在返回对象类上

@Api

• value - 字段说明
• description - 注释说明这个类

@ApiModelProperty的用法

• value–字段说明
• name–重写属性名字
• dataType–重写属性类型
• required–是否必填
• example–举例说明
• hidden–隐藏

@ApiOperation

• value - 字段说明
• notes - 注释说明
• httpMethod - 说明这个方法被请求的方式
• response - 方法的返回值的类型

@EnableSwagger2

• 表示开启swagger