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","[email protected]"))// 联系
                .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 多个请求参数

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

• http://localhost:8080/swagger-ui.html#/ 访问api文档
• http://localhost:8080/v2/api-docs 访问json数据，这个接下来生成静态文档会用到

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

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格式文档