swagger的API自动生成文档、自动生成其他语言请求文档、所有请求导入postman

最新推荐文章于 2025-07-03 18:00:00 发布

原创最新推荐文章于 2025-07-03 18:00:00 发布 · 3.1k 阅读

2 ·

CC 4.0 BY-SA版权

java 同时被 2 个专栏收录

132 篇文章

订阅专栏

swagger

1 篇文章

订阅专栏

本文介绍如何使用Swagger自动生成API文档，并演示了如何将其导入Postman进行本地调试，还介绍了如何生成不同语言的客户端代码。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

一、swagger的API自动生成文档

1.maven引入swagger的相关jar

<swagger.version>2.6.1</swagger.version>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

2.配置SwaggerConfig 配置类

@Profile指定了只在dev test 环境有效，正式环境是访问不到的

也可以指定Header参数

@EnableSwagger2
@Configuration
@Profile({"dev", "test"})
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {

        //添加head参数start
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        tokenPar.name("client").description("渠道").defaultValue("SENIOR_TEACH").modelRef(new ModelRef("string"))
                .parameterType("header").required(true).build();
        pars.add(tokenPar.build());
        //添加head参数end

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lexue.edu"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Lexue User Module APIs")
                .description("Lexue User Module APIs")
                .version("1.0")
                .build();
    }

}

3.Controller类中增加文档标签

@Api @ApiOperation @ApiParam @ApiIgnore等

@Api(tags={"account"})
@RestController("accountController")
@Slf4j
public class AccountController {

    @ApiOperation(value = "查询用户余额",notes = "查询用户余额信息")
    @GetMapping(value="/account/{version}/balance")
    @UserLoggedCheck
    public AppResponse<AccountBalanceResponse> balance(@PathVariable("version") String version
            ,@ApiIgnore UserLoggedInfo userLoggedInfo){
        AppResponse response;

        response.setTsrp(System.currentTimeMillis());
        return response;

    }

    @GetMapping(value="/account/{version}/trans")
    @UserLoggedCheck
    @ApiOperation(value = "查询账户交易记录", notes = "查询账户交易记录，分页查询")
    public AppResponse<PageContent<AccountTransResponse>> trans(@PathVariable("version") String version
            ,@ApiParam(value = "当前页码",defaultValue = "1") @RequestParam(name = "cur",required = false,defaultValue = "1") int cur
            ,@ApiParam(value = "页面大小",defaultValue = "20") @RequestParam(name = "size",required = false,defaultValue = "20") int size
            ,@ApiIgnore UserLoggedInfo userLoggedInfo){
        AppResponse response;
        response.setTsrp(System.currentTimeMillis());
        return response;
    }
}

4.返回对象中增加swagger的标签

@ApiModelProperty

@Data
@JsonInclude(value = JsonInclude.Include.NON_NULL)
public class AccountTransResponse {

   @ApiModelProperty(value = "交易类型",example = "1")
   @JsonProperty("trtp")
   private TransactionRecordType transType ;

   @ApiModelProperty(value = "交易流水",example = "ls1323454561313")
   @JsonProperty("trsl")
   private String transSerial;

   @ApiModelProperty(value = "交易金额,单位分",example = "10000")
   @JsonProperty("trac")
   private long transAccount  ;

   @ApiModelProperty(value = "交易时间戳，毫秒",example = "1515746099000")
   @JsonProperty("trts")
   private long transTimestamp;

}