Springboot+swagger2的接口文档开发

Posted 2021-12-02 txppp

一、创建一个SpringBoot项目

1.

2.

3.

4. 把web里的web选中，SQL里选择自己需要的，点击next

二、创建各项所需的controller，configure等

1. 项目布局

2. 引入的包

       <!-- swagger2所用的包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

3. swagger配置类，配置类有多种方法，试过使用.apis(RequestHandlerSelectors.basePackage("com.txp.controller"))的方法扫描controller包的位置，结果访问swagger页面的时候显示不出来，应该是没有扫描到，所以使用了下面的方法，即所有使用@ApiOperation注解的类都会被扫描

 1 package com.txp.swagger2.configue;
 2 
 3 import io.swagger.annotations.ApiOperation;
 4 import org.springframework.context.annotation.Bean;
 5 import org.springframework.context.annotation.Configuration;
 6 import springfox.documentation.builders.ApiInfoBuilder;
 7 import springfox.documentation.builders.RequestHandlerSelectors;
 8 import springfox.documentation.service.ApiInfo;
 9 import springfox.documentation.spi.DocumentationType;
10 import springfox.documentation.spring.web.plugins.Docket;
11 import springfox.documentation.swagger2.annotations.EnableSwagger2;
12 
13 // 用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。
14 @Configuration
15 @EnableSwagger2
16 public class Swagger {
17 
18     @Bean
19     public Docket api(){
20         return new Docket(DocumentationType.SWAGGER_2)
21                 .apiInfo(apiInfo())
22                 .select()
23                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
24                 .build();
25     }
26 
27     private ApiInfo apiInfo(){
28         return new ApiInfoBuilder()
29                 .title("springboot利用swagger构建api文档") // 页面标题
30                 .description("简单优雅的restful风格") // 创建人
31                 .termsOfServiceUrl("")
32                 .version("1.0")// 版本号
33                 .description("测试springboot结合swagger2")// 描述
34                 .build();
35     }
36 }

View Code

4. 实体类User，JsonResult

 1 package com.txp.swagger2.configue;
 2 
 3 import java.util.Date;
 4 
 5 public class User {
 6 
 7     private int id;
 8     private String username;
 9     private int age;
10     private Date ctm;
11 
12     public int getId() {
13         return id;
14     }
15 
16     public void setId(int id) {
17         this.id = id;
18     }
19 
20     public String getUsername() {
21         return username;
22     }
23 
24     public void setUsername(String username) {
25         this.username = username;
26     }
27 
28     public int getAge() {
29         return age;
30     }
31 
32     public void setAge(int age) {
33         this.age = age;
34     }
35 
36     public Date getCtm() {
37         return ctm;
38     }
39 
40     public void setCtm(Date ctm) {
41         this.ctm = ctm;
42     }
43 }

View Code

 1 package com.txp.swagger2.configue;
 2 
 3 public class JsonResult {
 4 
 5     private String status = null;
 6 
 7     private Object result = null;
 8 
 9     public String getStatus() {
10         return status;
11     }
12 
13     public void setStatus(String status) {
14         this.status = status;
15     }
16 
17     public Object getResult() {
18         return result;
19     }
20 
21     public void setResult(Object result) {
22         this.result = result;
23     }
24 }

View Code

5. UserController类

 1 package com.txp.swagger2.controller;
 2 
 3 import com.txp.swagger2.configue.JsonResult;
 4 import com.txp.swagger2.configue.User;
 5 import io.swagger.annotations.ApiImplicitParam;
 6 import io.swagger.annotations.ApiOperation;
 7 import org.springframework.http.ResponseEntity;
 8 import org.springframework.web.bind.annotation.RequestMapping;
 9 import org.springframework.web.bind.annotation.RequestMethod;
10 import org.springframework.web.bind.annotation.RestController;
11 
12 import java.util.*;
13 
14 @RestController
15 public class UserController {
16 
17     static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer,User>());
18 
19     @ApiOperation(value = "获取用户详细信息",notes = "根据url的id来获取用户详细信息")
20     @ApiImplicitParam(name = "id",value = "用户ID",required = true, dataType = "Integer", paramType = "path")
21     @RequestMapping(value = "users",method = RequestMethod.GET)
22     public ResponseEntity<JsonResult> getUserById(){
23         JsonResult r = new JsonResult();
24         try{
25             List<User> userList = new ArrayList<User>(users.values());
26             r.setResult(userList);
27             r.setStatus("ok");
28         } catch (Exception e){
29             r.setResult(e.getClass().getName() + ":" + e.getMessage());
30             r.setStatus("error");
31             e.printStackTrace();
32         }
33 
34         return ResponseEntity.ok(r);
35     }
36 }

View Code

6. 启动类配置

 1 package com.txp.swagger2;
 2 
 3 import org.springframework.boot.SpringApplication;
 4 import org.springframework.boot.autoconfigure.SpringBootApplication;
 5 import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
 6 import springfox.documentation.swagger2.annotations.EnableSwagger2;
 7 
 8 @SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})
 9 // 加上注解@EnableSwagger2 表示开启Swagger
10 @EnableSwagger2
11 public class Swagger2Application {
12 
13     public static void main(String[] args) {
14 
15         SpringApplication.run(Swagger2Application.class, args);
16     }
17 
18 }

View Code

三、结果

四、Swagger注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数

补充常用参数、属性

备注（各参数意义）：

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

@ApiImplicitParam参数：

属性	取值	作用
paramType		查询参数类型
path	以地址的形式提交数据
query	直接跟参数完成自动映射赋值
body	以流的形式提交 仅支持POST
header	参数在request headers 里边提交
form	以form表单的形式提交 仅支持POST
dataType		参数的数据类型 只作为标志说明，并没有实际验证
Long	
String	
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
true	必填
false	非必填
defaultValue		默认值