25.JavaWeb-接口文档Swagger

1.Swagger

        swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。

1.1 接口文档

        接口文档是用于描述API的一份文档，它包含了API的详细信息，包括API的请求和响应参数、接口路径、请求方法、数据类型、返回数据结构等。

2.swagger常用注解

@RestController
@Api(tags = "图书管理API", description = "用于管理图书馆中图书的API")
public class BookController {
    @ApiOperation(value = "根据ID获取图书", notes = "根据图书ID从图书馆中获取图书")
    @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/books/{id}")
    public ResponseEntity<Book> getBookById(@PathVariable Long id) {
        // 省略业务逻辑
    }
    @ApiOperation(value = "更新图书", notes = "更新图书馆中现有的图书")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "图书ID", required = true, dataType = "Long", paramType = "path"),
            @ApiImplicitParam(name = "book", value = "图书对象", required = true, dataType = "Book", paramType = "body")
    })
    @PutMapping("/books/{id}")
    public ResponseEntity<Book> updateBook(@PathVariable Long id, @RequestBody Book book){
        // 省略业务逻辑
    }
}

注解	位置	说明
@Api	类上	用于描述该类是"图书管理API"，说明整个API的主要作用。
@ApiOperation	方法上	用于给API方法增加说明，描述每个方法的作用。例如，getBookById方法用于根据ID获取图书，addBook方法用于添加新图书。
@ApiImplicitParam	方法入参	用于给方法的入参增加说明，描述参数的作用和数据类型。在getBookById和deleteBook方法中，都有一个参数id，通过该注解说明id的作用和数据类型。
@ApiImplicitParams	方法上	用于包含一组参数说明，可以在一个注解中同时描述多个参数。在updateBook方法中，使用该注解描述两个参数：id表示图书ID，book表示图书对象。

@Data
@ApiModel(value = "封装商品信息对象")
public class Goods implements Serializable {
    @ApiModelProperty(value = "商品id",dataType = "int")
    private Integer id;
}

@ApiModel	用在返回对象类上，描述一个Model的信息。在本例中，Book类可能是一个POJO类，用于描述图书的信息。
@ApiModelProperty	用于描述一个model的属性。在本例中，如果Book类有其他属性，可以使用该注解为这些属性增加说明。例如，书名、作者、出版日期等。

3.使用Swagger

        使用swagger时，只需要在需要生成接口文档的handler中使用相关注解，swagger就可以自动生成接口文档

3.1 导入swagger依赖

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--springfox-swagger-ui
    Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot
    项目的项目代码，自动生成JSON格式的描述文件。-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3.2 编写swagger配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("商品模块API文档")
                .description("采用restful风格接口")
                .version("1.0")
                .build();
    }
    @Bean
    public Docket docket(ApiInfo apiInfo) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage(
                        "com.mall.mall100.controller"))
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

4.访问swagger接口文档

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