Swagger - 自动生成接口文档

原创已于 2022-05-04 16:53:51 修改 · 4.3k 阅读

9 ·

CC 4.0 BY-SA版权

文章标签：

#java #java-ee

于 2022-05-04 11:19:58 首次发布

本文档介绍了如何在SpringBoot项目中使用Swagger来生成接口文档并进行调试。首先，通过引入Swagger的两个核心依赖springfox-swagger2和springfox-swagger-ui。接着，展示了如何使用@ApiModel和@ApiOperation等注解对实体类和Controller层的方法进行注解说明。然后，配置SwaggerUI的相关信息，包括项目信息和接口展示选择。最后，提供了访问SwaggerUI的URL，并给出了一个简单的实体类和Controller示例。通过这种方式，可以方便地进行前后端分离开发并简化接口调试过程。

Swagger
Swagger可以很方便的直接生成项目的接口，便于前后端的分离式开发，并且它还具备调试等功能，可以说十分方便。以这篇文章记录一些Swagger在Springboot项目开发中的使用。

1. 引入依赖

 <!--        swagger-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.7.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.7.0</version>
    </dependency>

2.Swagger接口注解

2.1 实体类

@ApiModel为实体类的解释说明

@ApiModel("User实体类")
@Data
@Repository
public class User {
    @ApiModelProperty("用户的ID")
    private String userName;
    private String password;
    private User user;
}

2.2 Controller层

@Api为Controller类的解释说明
@ApiOperation为Controller类方法的解释说明

@Api("HelloController")
@RestController
public class HelloController {
    @ApiOperation("hello控制类")
    @RequestMapping(method = RequestMethod.GET, value = "/api/javainuse")
    public String sayHello() {
        return "Swagger Hello World";
    }
    @ApiOperation("测试登录")
    @RequestMapping(method = RequestMethod.POST,value = "/api/testLogin")
    public User send(String username, String password){
        User user = new User();
        User user1 = new User();
        user.setUserName(username);
        user.setPassword(password);
        user1.setUserName(username);
        user1.setPassword(password);
        user.setUser(user1);
        return user;
    }
}

3. Swagger配置层

在这里进行SwaggerUI界面的配置，显示一些相关信息。


@Configuration
@EnableSwagger2
public class SpringFoxConfig {
  
   
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .build();
    }
  
  
    //配置Swagger的信息 apiInfo
    private ApiInfo apiInfo(){
    //作者信息
        Contact contact = new Contact("yao","none","1482089698@qq.com");
        return new ApiInfo(
                "SwaggerDemo",
                "这是一个DEMO",
                "1.0",
                "http://localhost:8080",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}