Swagger注解生成Rest Api文档 并生成静态文档

Swagger注解生成Rest Api文档

1、添加配置类

@Configuration //spring boot配置注解
@EnableSwagger2 //启用swagger2功能注解
public class Swagger2Config extends WebMvcConfigurationSupport {
    @Bean
    public Docket createRestfulApi() {//api文档实例
        return new Docket(DocumentationType.SWAGGER_2)//文档类型:DocumentationType.SWAGGER_2
                .apiInfo(apiInfo())//api信息
                .select()//构建api选择器
                .apis(RequestHandlerSelectors.basePackage("com.topplus.vite.controller"))//api选择器选择api的包
                .paths(PathSelectors.any())//api选择器选择包路径下任何api显示在文档中
                .build();//创建文档
    }

    private ApiInfo apiInfo() {//接口的相关信息
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful接口")
                .description("测试接口描述")
                .termsOfServiceUrl("termsOfServiceUrl")
                .contact("foo") //.contact(new Contact("xxx", "http://www.baidu.com","xxxxxx@qq.com"))// 联系
                .version("1.0")
                .license("testLicenseInfo")
                .licenseUrl("http://springfox.github.io/springfox/docs/current/")
                .build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

2、maven依赖

<!--swagge依赖-->
<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、在controller加注解

示例:

@Api(value="TransportRecordAPI",tags={"TransportRecordAPI"})//接口简要标注
@RestController
@RequestMapping(value = {"api/vehicle", "backstage/vehicle"}, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public class TransportRecordController {
@Autowired
private TransportRecordService transportRecordService;

@ApiImplicitParams({
@ApiImplicitParam(paramType = "header", name = "Token", value = "token", dataType = "String", required = true,defaultValue = "123")})
//接口功能描述
@ApiOperation(value = "上传综合交通参数接口")
@PostMapping("uploadTransport")
public Object uploadTransport(@RequestBody(required = false)TransportRecordEntity transportRecordEntity) {
return transportRecordService.recordSave(transportRecordEntity);

}

}

@Api:修饰整个类,描述Controller的作用

@ApiOperation:描述一个类的一个方法,或者说一个接口

@ApiParam:单个参数描述

@ApiModel:用对象来接收参数

@ApiProperty:用对象接收参数时,描述对象的一个字段

@ApiResponse:HTTP响应其中1个描述

@ApiResponses:HTTP响应整体描述

@ApiIgnore:使用该注解忽略这个API

@ApiError :发生错误返回的信息

@ApiParamImplicitL:一个请求参数

@ApiParamsImplicit 多个请求参数

完成以上就可以启动项目然后访问。

##================分割线====================#

4、使用Swagger2Markup生成静态文档

在pom文件中添加插件

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.1</version>
    <configuration>
        <!-- api-docs访问url -->
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <!-- 生成为单个文档,输出路径 -->
        <outputFile>src/docs/asciidoc/generated/all</outputFile>
        <!-- 生成为多个文档,输出路径 -->
        <!--<outputDir>src/docs/asciidoc/generated</outputDir>-->
        <config>
            <!-- wiki格式文档 -->
           <swagger2markup.markupLanguage>CONFLUENCE_MARKUP</swagger2markup.markupLanguage>
            <!-- ascii格式文档 -->
            <!--<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>-->
            <!-- markdown格式文档 -->
            <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>

            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
    </configuration>
</plugin>

使用方法:在Maven 中找到该插件运行它

5、效果图

markdown格式文档

 

  • 1
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值