25.JavaWeb-接口文档Swagger_java接口文档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){
        // 省略业务逻辑
    }
}

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

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